diff --git a/locales/ar/LC_MESSAGES/messages.po b/locales/ar/LC_MESSAGES/messages.po index f7e1fb3dc..c6abfe304 100644 --- a/locales/ar/LC_MESSAGES/messages.po +++ b/locales/ar/LC_MESSAGES/messages.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-01-18 07:31+0000\n" "Last-Translator: Youcef Guenaoua \n" "Language-Team: Arabic =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13506,7 +13508,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13514,24 +13516,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13539,22 +13541,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13565,65 +13567,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13631,106 +13633,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/ars/LC_MESSAGES/messages.po b/locales/ars/LC_MESSAGES/messages.po index 396e54968..4b9c0c3be 100644 --- a/locales/ars/LC_MESSAGES/messages.po +++ b/locales/ars/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: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -2846,7 +2846,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 #: ../source/specifications/dependency-specifiers.rst:29 -#: ../source/specifications/direct-url-data-structure.rst:342 +#: ../source/specifications/direct-url-data-structure.rst:344 #: ../source/specifications/version-specifiers.rst:1067 msgid "Examples" msgstr "" @@ -11793,7 +11793,7 @@ msgstr "" #: ../source/specifications/binary-distribution-format.rst:421 #: ../source/specifications/core-metadata.rst:848 #: ../source/specifications/dependency-specifiers.rst:476 -#: ../source/specifications/direct-url-data-structure.rst:392 +#: ../source/specifications/direct-url-data-structure.rst:394 #: ../source/specifications/direct-url.rst:67 #: ../source/specifications/entry-points.rst:164 #: ../source/specifications/externally-managed-environments.rst:472 @@ -13440,10 +13440,12 @@ msgstr "" #: ../source/specifications/direct-url-data-structure.rst:61 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)." +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:63 +#: ../source/specifications/direct-url-data-structure.rst:65 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 " @@ -13451,34 +13453,34 @@ msgid "" "``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:71 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "Archive URLs" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/direct-url-data-structure.rst:75 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/direct-url-data-structure.rst:76 +#: ../source/specifications/direct-url-data-structure.rst:78 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/direct-url-data-structure.rst:79 +#: ../source/specifications/direct-url-data-structure.rst:81 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:83 +#: ../source/specifications/direct-url-data-structure.rst:85 msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/direct-url-data-structure.rst:87 msgid "" "Any hash algorithm available via :py:mod:`hashlib` (specifically any that " "can be passed to :py:func:`hashlib.new()` and do not require additional " @@ -13487,13 +13489,13 @@ msgid "" "be included. At time of writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:91 +#: ../source/specifications/direct-url-data-structure.rst:93 msgid "" "A deprecated ``hash`` key (type ``string``) MAY be present for backwards " "compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13501,7 +13503,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13509,24 +13511,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13534,22 +13536,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13560,65 +13562,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13626,106 +13628,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/de/LC_MESSAGES/messages.po b/locales/de/LC_MESSAGES/messages.po index 989b9d362..56251c8a6 100644 --- a/locales/de/LC_MESSAGES/messages.po +++ b/locales/de/LC_MESSAGES/messages.po @@ -11,7 +11,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-02-20 01:04+0000\n" "Last-Translator: TheescapedShadow \n" "Language-Team: German =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13551,7 +13553,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13559,24 +13561,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13584,22 +13586,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13610,65 +13612,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13676,106 +13678,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/eo/LC_MESSAGES/messages.po b/locales/eo/LC_MESSAGES/messages.po index 27bc2a05b..92524c62c 100644 --- a/locales/eo/LC_MESSAGES/messages.po +++ b/locales/eo/LC_MESSAGES/messages.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2021-08-06 05:45+0000\n" "Last-Translator: meowmeowmeowcat \n" "Language-Team: Esperanto =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13865,7 +13867,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13873,24 +13875,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13898,22 +13900,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13924,65 +13926,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13990,106 +13992,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/es/LC_MESSAGES/messages.po b/locales/es/LC_MESSAGES/messages.po index b73d30a34..fc4689bcf 100644 --- a/locales/es/LC_MESSAGES/messages.po +++ b/locales/es/LC_MESSAGES/messages.po @@ -15,11 +15,11 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-03-13 13:26+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-04-12 02:01+0000\n" "Last-Translator: \"Edgar R. M.\" \n" -"Language-Team: Spanish \n" +"Language-Team: Spanish \n" "Language: es\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" @@ -997,6 +997,292 @@ msgid "" "io/posts/2013/07/setup-vs-requirement/." msgstr "" +#: ../source/discussions/package-formats.rst:5 +#, fuzzy +msgid "Package Formats" +msgstr "Índice de paquetes" + +#: ../source/discussions/package-formats.rst:7 +msgid "" +"This page discusses the file formats that are used to distribute Python " +"packages and the differences between them." +msgstr "" + +#: ../source/discussions/package-formats.rst:10 +msgid "" +"You will find files in two formats on package indices such as PyPI_: " +"**source distributions**, or **sdists** for short, and **binary " +"distributions**, commonly called **wheels**. For example, the `PyPI page " +"for pip 23.3.1 `_ lets you download two files, ``pip-23.3.1.tar." +"gz`` and ``pip-23.3.1-py3-none-any.whl``. The former is an sdist, the " +"latter is a wheel. As explained below, these serve different purposes. When " +"publishing a package on PyPI (or elsewhere), you should always upload both " +"an sdist and one or more wheel." +msgstr "" + +#: ../source/discussions/package-formats.rst:21 +#, fuzzy +msgid "What is a source distribution?" +msgstr "Paquete de Distribución" + +#: ../source/discussions/package-formats.rst:23 +msgid "" +"Conceptually, a source distribution is an archive of the source code in raw " +"form. Concretely, an sdist is a ``.tar.gz`` archive containing the source " +"code plus an additional special file called ``PKG-INFO``, which holds the " +"project metadata. The presence of this file helps packaging tools to be more " +"efficient by not needing to compute the metadata themselves. The ``PKG-" +"INFO`` file follows the format specified in :ref:`core-metadata` and is not " +"intended to be written by hand [#core-metadata-format]_." +msgstr "" + +#: ../source/discussions/package-formats.rst:31 +msgid "" +"You can thus inspect the contents of an sdist by unpacking it using standard " +"tools to work with tar archives, such as ``tar -xvf`` on UNIX platforms " +"(like Linux and macOS), or :ref:`the command line interface of Python's " +"tarfile module ` on any platform." +msgstr "" + +#: ../source/discussions/package-formats.rst:36 +msgid "" +"Sdists serve several purposes in the packaging ecosystem. When :ref:`pip`, " +"the standard Python package installer, cannot find a wheel to install, it " +"will fall back on downloading a source distribution, compiling a wheel from " +"it, and installing the wheel. Furthermore, sdists are often used as the " +"package source by downstream packagers (such as Linux distributions, Conda, " +"Homebrew and MacPorts on macOS, ...), who, for various reasons, may prefer " +"them over, e.g., pulling from a Git repository." +msgstr "" + +#: ../source/discussions/package-formats.rst:44 +msgid "" +"A source distribution is recognized by its file name, which has the form :" +"samp:`{package_name}-{version}.tar.gz`, e.g., ``pip-23.3.1.tar.gz``." +msgstr "" + +#: ../source/discussions/package-formats.rst:50 +msgid "" +"If you want technical details on the sdist format, read the :ref:`sdist " +"specification `." +msgstr "" + +#: ../source/discussions/package-formats.rst:55 +msgid "What is a wheel?" +msgstr "" + +#: ../source/discussions/package-formats.rst:57 +msgid "" +"Conceptually, a wheel contains exactly the files that need to be copied when " +"installing the package." +msgstr "" + +#: ../source/discussions/package-formats.rst:60 +msgid "" +"There is a big difference between sdists and wheels for packages with :term:" +"`extension modules `, written in compiled languages like " +"C, C++ and Rust, which need to be compiled into platform-dependent machine " +"code. With these packages, wheels do not contain source code (like C source " +"files) but compiled, executable code (like ``.so`` files on Linux or DLLs on " +"Windows)." +msgstr "" + +#: ../source/discussions/package-formats.rst:66 +msgid "" +"Furthermore, while there is only one sdist per version of a project, there " +"may be many wheels. Again, this is most relevant in the context of extension " +"modules. The compiled code of an extension module is tied to an operating " +"system and processor architecture, and often also to the version of the " +"Python interpreter (unless the :ref:`Python stable ABI ` " +"is used)." +msgstr "" + +#: ../source/discussions/package-formats.rst:72 +msgid "" +"For pure-Python packages, the difference between sdists and wheels is less " +"marked. There is normally one single wheel, for all platforms and Python " +"versions. Python is an interpreted language, which does not need ahead-of-" +"time compilation, so wheels contain ``.py`` files just like sdists." +msgstr "" + +#: ../source/discussions/package-formats.rst:77 +msgid "" +"If you are wondering about ``.pyc`` bytecode files: they are not included in " +"wheels, since they are cheap to generate, and including them would " +"unnecessarily force a huge number of packages to distribute one wheel per " +"Python version instead of one single wheel. Instead, installers like :ref:" +"`pip` generate them while installing the package." +msgstr "" + +#: ../source/discussions/package-formats.rst:83 +msgid "" +"With that being said, there are still important differences between sdists " +"and wheels, even for pure Python projects. Wheels are meant to contain " +"exactly what is to be installed, and nothing more. In particular, wheels " +"should never include tests and documentation, while sdists commonly do. " +"Also, the wheel format is more complex than sdist. For example, it includes " +"a special file -- called ``RECORD`` -- that lists all files in the wheel " +"along with a hash of their content, as a safety check of the download's " +"integrity." +msgstr "" + +#: ../source/discussions/package-formats.rst:91 +msgid "" +"At a glance, you might wonder if wheels are really needed for \"plain and " +"basic\" pure Python projects. Keep in mind that due to the flexibility of " +"sdists, installers like pip cannot install from sdists directly -- they need " +"to first build a wheel, by invoking the :term:`build backend` that the sdist " +"specifies (the build backend may do all sorts of transformations while " +"building the wheel, such as compiling C extensions). For this reason, even " +"for a pure Python project, you should always upload *both* an sdist and a " +"wheel to PyPI or other package indices. This makes installation much faster " +"for your users, since a wheel is directly installable. By only including " +"files that must be installed, wheels also make for smaller downloads." +msgstr "" + +#: ../source/discussions/package-formats.rst:102 +msgid "" +"On the technical level, a wheel is a ZIP archive (unlike sdists which are " +"TAR archives). You can inspect its contents by unpacking it as a normal ZIP " +"archive, e.g., using ``unzip`` on UNIX platforms like Linux and macOS, " +"``Expand-Archive`` in Powershell on Windows, or :ref:`the command line " +"interface of Python's zipfile module `. This can " +"be very useful to check that the wheel includes all the files you need it to." +msgstr "" + +#: ../source/discussions/package-formats.rst:109 +msgid "" +"Inside a wheel, you will find the package's files, plus an additional " +"directory called :samp:`{package_name}-{version}.dist-info`. This directory " +"contains various files, including a ``METADATA`` file which is the " +"equivalent of ``PKG-INFO`` in sdists, as well as ``RECORD``. This can be " +"useful to ensure no files are missing from your wheels." +msgstr "" + +#: ../source/discussions/package-formats.rst:115 +msgid "" +"The file name of a wheel (ignoring some rarely used features) looks like " +"this: :samp:`{package_name}-{version}-{python_tag}-{abi_tag}-{platform_tag}." +"whl`. This naming convention identifies which platforms and Python versions " +"the wheel is compatible with. For example, the name ``pip-23.3.1-py3-none-" +"any.whl`` means that:" +msgstr "" + +#: ../source/discussions/package-formats.rst:121 +msgid "" +"(``py3``) This wheel can be installed on any implementation of Python 3, " +"whether CPython, the most widely used Python implementation, or an " +"alternative implementation like PyPy_;" +msgstr "" + +#: ../source/discussions/package-formats.rst:124 +msgid "(``none``) It does not depend on the Python version;" +msgstr "" + +#: ../source/discussions/package-formats.rst:125 +msgid "(``any``) It does not depend on the platform." +msgstr "" + +#: ../source/discussions/package-formats.rst:127 +msgid "" +"The pattern ``py3-none-any`` is common for pure Python projects. Packages " +"with extension modules typically ship multiple wheels with more complex tags." +msgstr "" + +#: ../source/discussions/package-formats.rst:130 +msgid "" +"All technical details on the wheel format can be found in the :ref:`wheel " +"specification `." +msgstr "" + +#: ../source/discussions/package-formats.rst:138 +#, fuzzy +msgid "What about eggs?" +msgstr "¿Qué pasa con los pasos de construcción personalizados?" + +#: ../source/discussions/package-formats.rst:140 +msgid "" +"\"Egg\" is an old package format that has been replaced with the wheel " +"format. It should not be used anymore. Since August 2023, PyPI `rejects egg " +"uploads `_." +msgstr "" + +#: ../source/discussions/package-formats.rst:144 +msgid "Here's a breakdown of the important differences between wheel and egg." +msgstr "" + +#: ../source/discussions/package-formats.rst:146 +msgid "" +"The egg format was introduced by :ref:`setuptools` in 2004, whereas the " +"wheel format was introduced by :pep:`427` in 2012." +msgstr "" + +#: ../source/discussions/package-formats.rst:149 +msgid "" +"Wheel has an :doc:`official standard specification `. Egg did not." +msgstr "" + +#: ../source/discussions/package-formats.rst:152 +msgid "" +"Wheel is a :term:`distribution ` format, i.e a " +"packaging format. [#wheel-importable]_ Egg was both a distribution format " +"and a runtime installation format (if left zipped), and was designed to be " +"importable." +msgstr "" + +#: ../source/discussions/package-formats.rst:156 +msgid "" +"Wheel archives do not include ``.pyc`` files. Therefore, when the " +"distribution only contains Python files (i.e. no compiled extensions), and " +"is compatible with Python 2 and 3, it's possible for a wheel to be " +"\"universal\", similar to an :term:`sdist `." +msgstr "" + +#: ../source/discussions/package-formats.rst:161 +msgid "" +"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +msgstr "" + +#: ../source/discussions/package-formats.rst:164 +msgid "" +"Wheel has a :ref:`richer file naming convention `. A " +"single wheel archive can indicate its compatibility with a number of Python " +"language versions and implementations, ABIs, and system architectures." +msgstr "" + +#: ../source/discussions/package-formats.rst:168 +msgid "" +"Wheel is versioned. Every wheel file contains the version of the wheel " +"specification and the implementation that packaged it." +msgstr "" + +#: ../source/discussions/package-formats.rst:171 +msgid "" +"Wheel is internally organized by `sysconfig path type `_, therefore making it " +"easier to convert to other formats." +msgstr "" + +#: ../source/discussions/package-formats.rst:177 +msgid "" +"This format is email-based. Although this would be unlikely to be chosen " +"today, backwards compatibility considerations lead to it being kept as the " +"canonical format. From the user point of view, this is mostly invisible, " +"since the metadata is specified by the user in a way understood by the build " +"backend, typically ``[project]`` in ``pyproject.toml``, and translated by " +"the build backend into ``PKG-INFO``." +msgstr "" + +#: ../source/discussions/package-formats.rst:184 +msgid "" +"Circumstantially, in some cases, wheels can be used as an importable runtime " +"format, although :ref:`this is not officially supported at this time `." +msgstr "" + #: ../source/discussions/pip-vs-easy-install.rst:6 msgid "pip vs easy_install" msgstr "" @@ -1918,99 +2204,6 @@ msgid "" "`_. For a humoristic take, read about ZeroVer_." msgstr "" -#: ../source/discussions/wheel-vs-egg.rst:5 -msgid "Wheel vs Egg" -msgstr "" - -#: ../source/discussions/wheel-vs-egg.rst:7 -msgid "" -":term:`Wheel` and :term:`Egg` are both packaging formats that aim to support " -"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 "" - -#: ../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 "" - -#: ../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 "" - -#: ../source/discussions/wheel-vs-egg.rst:17 -msgid "" -"Here's a breakdown of the important differences between :term:`Wheel` and :" -"term:`Egg`." -msgstr "" - -#: ../source/discussions/wheel-vs-egg.rst:20 -msgid "" -":term:`Wheel` has an :doc:`official standard specification `. :term:`Egg` did not." -msgstr "" - -#: ../source/discussions/wheel-vs-egg.rst:24 -msgid "" -":term:`Wheel` is a :term:`distribution ` format, i.e a " -"packaging format. [1]_ :term:`Egg` was both a distribution format and a " -"runtime installation format (if left zipped), and was designed to be " -"importable." -msgstr "" - -#: ../source/discussions/wheel-vs-egg.rst:28 -msgid "" -":term:`Wheel` archives do not include .pyc files. Therefore, when the " -"distribution only contains Python files (i.e. no compiled extensions), and " -"is compatible with Python 2 and 3, it's possible for a wheel to be " -"\"universal\", similar to an :term:`sdist `." -msgstr "" - -#: ../source/discussions/wheel-vs-egg.rst:33 -msgid "" -":term:`Wheel` uses :pep:`PEP376-compliant <376>` ``.dist-info`` directories. " -"Egg used ``.egg-info``." -msgstr "" - -#: ../source/discussions/wheel-vs-egg.rst:36 -msgid "" -":term:`Wheel` has a :pep:`richer file naming convention <425>`. A single " -"wheel archive can indicate its compatibility with a number of Python " -"language versions and implementations, ABIs, and system architectures." -msgstr "" - -#: ../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 "" - -#: ../source/discussions/wheel-vs-egg.rst:43 -msgid "" -":term:`Wheel` is internally organized by `sysconfig path type `_, therefore making " -"it easier to convert to other formats." -msgstr "" - -#: ../source/discussions/wheel-vs-egg.rst:47 -msgid "" -":term:`Egg` uploads have been disabled for upload to PyPI, per :pep:`715`. " -"Read the `deprecation notice `_ for more information." -msgstr "" - -#: ../source/discussions/wheel-vs-egg.rst:53 -#: ../source/discussions/package-formats.rst:184 -msgid "" -"Circumstantially, in some cases, wheels can be used as an importable runtime " -"format, although :ref:`this is not officially supported at this time `." -msgstr "" - #: ../source/flow.rst:3 msgid "The Packaging Flow" msgstr "" @@ -2309,11 +2502,12 @@ msgstr "Distribución Construida" msgid "" "A :term:`Distribution ` format containing files and " "metadata that only need to be moved to the correct location on the target " -"system, to be installed. :term:`Wheel` is such a format, whereas distutil's :" -"term:`Source Distribution ` is not, in " -"that it requires a build step before it can be installed. This format does " -"not imply that Python files have to be precompiled (:term:`Wheel` " -"intentionally does not include compiled Python files)." +"system, to be installed. :term:`Wheel` is such a format, whereas :term:" +"`Source Distribution ` is not, in that " +"it requires a build step before it can be installed. This format does not " +"imply that Python files have to be precompiled (:term:`Wheel` intentionally " +"does not include compiled Python files). See :ref:`package-formats` for more " +"information." msgstr "" #: ../source/glossary.rst:56 @@ -2347,16 +2541,14 @@ msgstr "" #: ../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 `_" +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." msgstr "" -#: ../source/glossary.rst:79 ../source/glossary.rst:78 +#: ../source/glossary.rst:78 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:82 ../source/glossary.rst:81 +#: ../source/glossary.rst:81 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 " @@ -2365,11 +2557,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:89 ../source/glossary.rst:88 +#: ../source/glossary.rst:88 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:92 ../source/glossary.rst:91 +#: ../source/glossary.rst:91 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 " @@ -2378,17 +2570,17 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:98 ../source/glossary.rst:97 +#: ../source/glossary.rst:97 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:101 ../source/glossary.rst:100 +#: ../source/glossary.rst:100 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:104 ../source/glossary.rst:103 +#: ../source/glossary.rst:103 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 " @@ -2397,50 +2589,50 @@ msgid "" "package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:109 ../source/glossary.rst:108 +#: ../source/glossary.rst:108 msgid "Module" msgstr "Módulo" -#: ../source/glossary.rst:112 ../source/glossary.rst:111 +#: ../source/glossary.rst:111 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:115 ../source/glossary.rst:114 +#: ../source/glossary.rst:114 msgid "Package Index" msgstr "Índice de paquetes" -#: ../source/glossary.rst:118 ../source/glossary.rst:117 +#: ../source/glossary.rst:117 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:121 ../source/glossary.rst:120 +#: ../source/glossary.rst:120 msgid "Per Project Index" msgstr "Índice por proyecto" -#: ../source/glossary.rst:124 ../source/glossary.rst:123 +#: ../source/glossary.rst:123 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:128 ../source/guides/hosting-your-own-index.rst:62 -#: ../source/guides/index-mirrors-and-caches.rst:52 ../source/glossary.rst:127 +#: ../source/glossary.rst:127 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 msgid "Project" msgstr "Proyecto" -#: ../source/glossary.rst:131 ../source/glossary.rst:130 +#: ../source/glossary.rst:130 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:135 ../source/glossary.rst:134 +#: ../source/glossary.rst:134 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -2449,7 +2641,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:141 ../source/glossary.rst:140 +#: ../source/glossary.rst:140 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -2457,7 +2649,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:146 ../source/glossary.rst:145 +#: ../source/glossary.rst:145 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 " @@ -2465,21 +2657,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:152 ../source/glossary.rst:151 +#: ../source/glossary.rst:151 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:155 ../source/glossary.rst:154 +#: ../source/glossary.rst:154 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:158 ../source/glossary.rst:157 +#: ../source/glossary.rst:157 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:161 ../source/glossary.rst:160 +#: ../source/glossary.rst:160 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 " @@ -2489,48 +2681,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:170 ../source/glossary.rst:169 +#: ../source/glossary.rst:169 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:173 ../source/glossary.rst:172 +#: ../source/glossary.rst:172 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:176 ../source/glossary.rst:175 +#: ../source/glossary.rst:175 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:179 ../source/glossary.rst:178 +#: ../source/glossary.rst:178 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:183 ../source/glossary.rst:182 +#: ../source/glossary.rst:182 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:186 ../source/glossary.rst:185 +#: ../source/glossary.rst:185 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:188 ../source/glossary.rst:187 +#: ../source/glossary.rst:187 msgid "Release" msgstr "" -#: ../source/glossary.rst:191 ../source/glossary.rst:190 +#: ../source/glossary.rst:190 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:194 ../source/glossary.rst:193 +#: ../source/glossary.rst:193 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2538,11 +2730,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:199 ../source/glossary.rst:198 +#: ../source/glossary.rst:198 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:202 ../source/glossary.rst:201 +#: ../source/glossary.rst:201 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2551,11 +2743,11 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:208 ../source/glossary.rst:207 +#: ../source/glossary.rst:207 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:211 ../source/glossary.rst:210 +#: ../source/glossary.rst:210 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " "Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " @@ -2563,56 +2755,55 @@ msgid "" "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" -#: ../source/glossary.rst:216 ../source/glossary.rst:215 +#: ../source/glossary.rst:215 msgid "Requirements File" msgstr "Archivo de requisitos" -#: ../source/glossary.rst:219 ../source/glossary.rst:218 +#: ../source/glossary.rst:218 msgid "" "A file containing a list of :term:`Requirements ` that can be " "installed using :ref:`pip`. For more information, see the :ref:`pip` docs " "on :ref:`pip:Requirements Files`." msgstr "" -#: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:59 #: ../source/glossary.rst:222 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" -#: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:80 #: ../source/glossary.rst:223 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" -#: ../source/glossary.rst:227 ../source/glossary.rst:226 +#: ../source/glossary.rst:226 msgid "" "The project specification files for :ref:`distutils` and :ref:`setuptools`. " "See also :term:`pyproject.toml`." msgstr "" -#: ../source/glossary.rst:230 ../source/glossary.rst:229 +#: ../source/glossary.rst:229 msgid "Source Archive" msgstr "Archivo Fuente" -#: ../source/glossary.rst:233 ../source/glossary.rst:232 +#: ../source/glossary.rst:232 msgid "" "An archive containing the raw source code for a :term:`Release`, prior to " "creation of a :term:`Source Distribution ` or :term:`Built Distribution`." msgstr "" -#: ../source/glossary.rst:237 ../source/glossary.rst:236 +#: ../source/glossary.rst:236 msgid "Source Distribution (or \"sdist\")" msgstr "" -#: ../source/glossary.rst:240 +#: ../source/glossary.rst:239 msgid "" "A :term:`distribution ` format (usually generated " "using ``python -m build --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`." +"generating a :term:`Built Distribution`. See :ref:`package-formats` for more " +"information." msgstr "" #: ../source/glossary.rst:245 @@ -2658,17 +2849,15 @@ msgstr "" #: ../source/glossary.rst:269 msgid "" -"A :term:`Built Distribution` format introduced by an official :doc:`standard " -"specification `, which is " -"intended to replace the :term:`Egg` format. Wheel is currently supported " -"by :ref:`pip`." +"The standard :term:`Built Distribution` format. See :ref:`package-formats` " +"for more information." msgstr "" -#: ../source/glossary.rst:274 ../source/glossary.rst:271 +#: ../source/glossary.rst:271 msgid "Working Set" msgstr "" -#: ../source/glossary.rst:277 ../source/glossary.rst:274 +#: ../source/glossary.rst:274 msgid "" "A collection of :term:`distributions ` available for " "importing. These are the distributions that are on the `sys.path` variable. " @@ -2820,7 +3009,7 @@ msgstr "Descripción" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 #: ../source/specifications/dependency-specifiers.rst:29 -#: ../source/specifications/direct-url-data-structure.rst:342 +#: ../source/specifications/direct-url-data-structure.rst:344 #: ../source/specifications/version-specifiers.rst:1067 msgid "Examples" msgstr "Ejemplos" @@ -11293,44 +11482,36 @@ msgstr "" msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:88 #: ../source/specifications/binary-distribution-format.rst:90 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 #: ../source/specifications/binary-distribution-format.rst:92 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:94 #: ../source/specifications/binary-distribution-format.rst:96 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:94 #: ../source/specifications/binary-distribution-format.rst:96 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 #: ../source/specifications/binary-distribution-format.rst:99 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 #: ../source/specifications/binary-distribution-format.rst:99 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:122 #: ../source/specifications/binary-distribution-format.rst:124 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 #: ../source/specifications/binary-distribution-format.rst:102 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " @@ -11340,7 +11521,6 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:107 #: ../source/specifications/binary-distribution-format.rst:109 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " @@ -11348,7 +11528,6 @@ msgid "" "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:114 #: ../source/specifications/binary-distribution-format.rst:116 msgid "" "Build numbers are not a part of the distribution version and thus are " @@ -11357,7 +11536,6 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:119 #: ../source/specifications/binary-distribution-format.rst:121 msgid "" "Due to this limitation, new distributions which need to be referenced " @@ -11366,39 +11544,32 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:125 #: ../source/specifications/binary-distribution-format.rst:127 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:125 #: ../source/specifications/binary-distribution-format.rst:127 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:128 -#: ../source/specifications/platform-compatibility-tags.rst:20 #: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/binary-distribution-format.rst:130 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:131 -#: ../source/specifications/platform-compatibility-tags.rst:23 #: ../source/specifications/binary-distribution-format.rst:133 +#: ../source/specifications/platform-compatibility-tags.rst:23 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/binary-distribution-format.rst:133 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:133 #: ../source/specifications/binary-distribution-format.rst:135 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " @@ -11407,7 +11578,6 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:138 #: ../source/specifications/binary-distribution-format.rst:140 msgid "" "The last three components of the filename before the extension are called " @@ -11415,12 +11585,10 @@ msgid "" "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:143 #: ../source/specifications/binary-distribution-format.rst:145 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:145 #: ../source/specifications/binary-distribution-format.rst:147 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" @@ -11428,7 +11596,6 @@ msgid "" "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:148 #: ../source/specifications/binary-distribution-format.rst:150 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " @@ -11440,7 +11607,6 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 #: ../source/specifications/binary-distribution-format.rst:157 msgid "" "Version numbers should be normalised according to the :ref:`Version " @@ -11448,14 +11614,12 @@ msgid "" "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:157 #: ../source/specifications/binary-distribution-format.rst:159 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:160 #: ../source/specifications/binary-distribution-format.rst:162 msgid "" "Tools producing wheels should verify that the filename components do not " @@ -11463,7 +11627,6 @@ msgid "" "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 #: ../source/specifications/binary-distribution-format.rst:165 msgid "" "The archive filename is Unicode. It will be some time before the tools are " @@ -11471,7 +11634,6 @@ msgid "" "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:167 #: ../source/specifications/binary-distribution-format.rst:169 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " @@ -11479,12 +11641,10 @@ msgid "" "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 #: ../source/specifications/binary-distribution-format.rst:175 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 #: ../source/specifications/binary-distribution-format.rst:177 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " @@ -11492,7 +11652,6 @@ msgid "" "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:179 #: ../source/specifications/binary-distribution-format.rst:181 msgid "" "``/``, the root of the archive, contains all files to be installed in " @@ -11500,12 +11659,10 @@ msgid "" "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:182 #: ../source/specifications/binary-distribution-format.rst:184 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:183 #: ../source/specifications/binary-distribution-format.rst:185 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" @@ -11514,7 +11671,6 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 #: ../source/specifications/binary-distribution-format.rst:189 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" @@ -11522,33 +11678,28 @@ msgid "" "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:191 #: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 #: ../source/specifications/binary-distribution-format.rst:195 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:203 #: ../source/specifications/binary-distribution-format.rst:205 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:204 #: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:206 #: ../source/specifications/binary-distribution-format.rst:208 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " @@ -11556,20 +11707,17 @@ msgid "" "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 #: ../source/specifications/binary-distribution-format.rst:211 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:211 #: ../source/specifications/binary-distribution-format.rst:213 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 #: ../source/specifications/binary-distribution-format.rst:214 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " @@ -11577,19 +11725,16 @@ msgid "" "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:215 #: ../source/specifications/binary-distribution-format.rst:217 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:217 #: ../source/specifications/binary-distribution-format.rst:219 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:219 #: ../source/specifications/binary-distribution-format.rst:221 msgid "" "This version of the wheel specification is based on the distutils install " @@ -11598,32 +11743,27 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:226 -#: ../source/specifications/recording-installed-packages.rst:23 #: ../source/specifications/binary-distribution-format.rst:228 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:228 #: ../source/specifications/binary-distribution-format.rst:230 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:230 #: ../source/specifications/binary-distribution-format.rst:232 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:232 #: ../source/specifications/binary-distribution-format.rst:234 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 #: ../source/specifications/binary-distribution-format.rst:235 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " @@ -11633,25 +11773,21 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 #: ../source/specifications/binary-distribution-format.rst:241 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:240 #: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 #: ../source/specifications/binary-distribution-format.rst:244 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:245 #: ../source/specifications/binary-distribution-format.rst:247 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " @@ -11660,12 +11796,10 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:252 #: ../source/specifications/binary-distribution-format.rst:254 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:254 #: ../source/specifications/binary-distribution-format.rst:256 msgid "" "Any file that is not normally installed inside site-packages goes into the ." @@ -11673,7 +11807,6 @@ msgid "" "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 #: ../source/specifications/binary-distribution-format.rst:264 msgid "" "The .data directory contains subdirectories with the scripts, headers, " @@ -11681,12 +11814,10 @@ msgid "" "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:268 #: ../source/specifications/binary-distribution-format.rst:270 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 #: ../source/specifications/binary-distribution-format.rst:272 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " @@ -11697,7 +11828,6 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:281 #: ../source/specifications/binary-distribution-format.rst:283 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " @@ -11706,7 +11836,6 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:286 #: ../source/specifications/binary-distribution-format.rst:288 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " @@ -11715,19 +11844,16 @@ msgid "" "as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:295 #: ../source/specifications/binary-distribution-format.rst:297 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:297 #: ../source/specifications/binary-distribution-format.rst:299 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 #: ../source/specifications/binary-distribution-format.rst:302 msgid "" "A wheel installer is not required to understand digital signatures but MUST " @@ -11736,46 +11862,38 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:305 #: ../source/specifications/binary-distribution-format.rst:307 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:307 #: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:308 #: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:309 #: ../source/specifications/binary-distribution-format.rst:311 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:310 #: ../source/specifications/binary-distribution-format.rst:312 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:314 -#: ../source/specifications/platform-compatibility-tags.rst:268 #: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/platform-compatibility-tags.rst:268 msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:318 #: ../source/specifications/binary-distribution-format.rst:320 msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:320 #: ../source/specifications/binary-distribution-format.rst:322 msgid "" "This specification does not have an opinion on how you should organize your " @@ -11786,12 +11904,10 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:329 #: ../source/specifications/binary-distribution-format.rst:331 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:331 #: ../source/specifications/binary-distribution-format.rst:333 msgid "" "Attached signatures are more convenient than detached signatures because " @@ -11801,12 +11917,10 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:339 #: ../source/specifications/binary-distribution-format.rst:341 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:341 #: ../source/specifications/binary-distribution-format.rst:343 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " @@ -11814,31 +11928,26 @@ msgid "" "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:347 #: ../source/specifications/binary-distribution-format.rst:349 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 #: ../source/specifications/binary-distribution-format.rst:351 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:352 #: ../source/specifications/binary-distribution-format.rst:354 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:357 #: ../source/specifications/binary-distribution-format.rst:359 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:359 #: ../source/specifications/binary-distribution-format.rst:361 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " @@ -11847,7 +11956,6 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:364 #: ../source/specifications/binary-distribution-format.rst:366 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" @@ -11856,7 +11964,6 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:369 #: ../source/specifications/binary-distribution-format.rst:371 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " @@ -11864,12 +11971,10 @@ msgid "" "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:377 #: ../source/specifications/binary-distribution-format.rst:379 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:379 #: ../source/specifications/binary-distribution-format.rst:381 msgid "" "Technically, due to the combination of supporting installation via simple " @@ -11879,7 +11984,6 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:385 #: ../source/specifications/binary-distribution-format.rst:387 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " @@ -11891,7 +11995,6 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 #: ../source/specifications/binary-distribution-format.rst:396 msgid "" "Secondly, while some Python software is written to support running directly " @@ -11910,7 +12013,6 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:411 #: ../source/specifications/binary-distribution-format.rst:413 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " @@ -11920,10 +12022,10 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:421 #: ../source/specifications/core-metadata.rst:848 #: ../source/specifications/dependency-specifiers.rst:476 -#: ../source/specifications/direct-url-data-structure.rst:392 +#: ../source/specifications/direct-url-data-structure.rst:394 #: ../source/specifications/direct-url.rst:67 #: ../source/specifications/entry-points.rst:164 #: ../source/specifications/externally-managed-environments.rst:472 @@ -11936,28 +12038,23 @@ msgstr "" #: ../source/specifications/source-distribution-format.rst:144 #: ../source/specifications/version-specifiers.rst:1264 #: ../source/specifications/virtual-environments.rst:54 -#: ../source/specifications/binary-distribution-format.rst:421 msgid "History" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:421 #: ../source/specifications/binary-distribution-format.rst:423 msgid "February 2013: This specification was approved through :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:422 #: ../source/specifications/binary-distribution-format.rst:424 msgid "" "February 2021: The rules on escaping in wheel filenames were revised, to " "bring them into line with what popular tools actually do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:427 #: ../source/specifications/binary-distribution-format.rst:429 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:429 #: ../source/specifications/binary-distribution-format.rst:431 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" @@ -13582,10 +13679,12 @@ msgstr "" #: ../source/specifications/direct-url-data-structure.rst:61 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)." +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:63 +#: ../source/specifications/direct-url-data-structure.rst:65 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 " @@ -13593,34 +13692,34 @@ msgid "" "``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:71 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "Archive URLs" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/direct-url-data-structure.rst:75 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/direct-url-data-structure.rst:76 +#: ../source/specifications/direct-url-data-structure.rst:78 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/direct-url-data-structure.rst:79 +#: ../source/specifications/direct-url-data-structure.rst:81 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:83 +#: ../source/specifications/direct-url-data-structure.rst:85 msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/direct-url-data-structure.rst:87 msgid "" "Any hash algorithm available via :py:mod:`hashlib` (specifically any that " "can be passed to :py:func:`hashlib.new()` and do not require additional " @@ -13629,13 +13728,13 @@ msgid "" "be included. At time of writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:91 +#: ../source/specifications/direct-url-data-structure.rst:93 msgid "" "A deprecated ``hash`` key (type ``string``) MAY be present for backwards " "compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13643,7 +13742,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13651,24 +13750,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13676,22 +13775,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13702,65 +13801,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13768,106 +13867,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." @@ -19498,2088 +19597,1776 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 -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:937 -msgid "" -"If the specified version identifier is a local version identifier, then the " -"local version labels of candidate versions MUST be considered when matching " -"versions, with the public version identifier being matched as described " -"above, and the local version label being checked for equivalence using a " -"strict string equality comparison." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:945 -#, fuzzy -msgid "Version exclusion" -msgstr "Versión" - -#: ../source/specifications/version-specifiers.rst:947 -msgid "" -"A version exclusion clause includes the version exclusion operator ``!=`` " -"and a version identifier." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:950 -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:963 -msgid "Inclusive ordered comparison" -msgstr "" - -#: ../source/specifications/version-specifiers.rst:965 -msgid "" -"An inclusive ordered comparison clause includes a comparison operator and a " -"version identifier, and will match any version where the comparison is " -"correct based on the relative position of the candidate version and the " -"specified version given the consistent ordering defined by the standard " -"`Version scheme`_." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:971 -msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:973 -#: ../source/specifications/version-specifiers.rst:1003 -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:976 -#: ../source/specifications/version-specifiers.rst:1006 -msgid "Local version identifiers are NOT permitted in this version specifier." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:980 -msgid "Exclusive ordered comparison" -msgstr "" - -#: ../source/specifications/version-specifiers.rst:982 -msgid "" -"The exclusive ordered comparisons ``>`` and ``<`` are similar to the " -"inclusive ordered comparisons in that they rely on the relative position of " -"the candidate version and the specified version given the consistent " -"ordering defined by the standard `Version scheme`_. However, they " -"specifically exclude pre-releases, post-releases, and local versions of the " -"specified version." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:988 -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 " -"that releases are later than a particular post release, including additional " -"post releases, by using ``>V.postN``. For example, ``>1.7`` will allow " -"``1.7.1`` but not ``1.7.0.post1`` and ``>1.7.post2`` will allow ``1.7.1`` " -"and ``1.7.0.post3`` but not ``1.7.0``." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:995 -msgid "" -"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " -"of the specified version." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:998 -msgid "" -"The exclusive ordered comparison ``=`` entry as part " -"of the URL fragment." +#: ../source/specifications/version-specifiers.rst:963 +msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:1127 +#: ../source/specifications/version-specifiers.rst:965 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 " -"version control system with hash based commit identifiers SHOULD be used. " -"Automated tools MAY omit warnings about missing hashes for version control " -"systems that do not provide hash based commit identifiers." +"An inclusive ordered comparison clause includes a comparison operator and a " +"version identifier, and will match any version where the comparison is " +"correct based on the relative position of the candidate version and the " +"specified version given the consistent ordering defined by the standard " +"`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1133 -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 " -"end of the URL using the ``@`` or the ``@#`` " -"notation." +#: ../source/specifications/version-specifiers.rst:971 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:1140 +#: ../source/specifications/version-specifiers.rst:973 +#: ../source/specifications/version-specifiers.rst:1003 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 " -"embedded as part of the URL. Secondly, the commit hash is included even when " -"retrieving based on a tag, in order to meet the requirement above that " -"*every* link should include a hash to make things harder to forge (creating " -"a malicious repo with a particular tag is easy, creating one with a specific " -"*hash*, less so)." +"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:1148 -#, fuzzy -msgid "Remote URL examples::" -msgstr "Por ejemplo::" +#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:1006 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" -#: ../source/specifications/version-specifiers.rst:1156 -msgid "File URLs" +#: ../source/specifications/version-specifiers.rst:980 +msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:1158 +#: ../source/specifications/version-specifiers.rst:982 msgid "" -"File URLs take the form of ``file:///``. If the ```` is " -"omitted it is assumed to be ``localhost`` and even if the ```` is " -"omitted the third slash MUST still exist. The ```` defines what the " -"file path on the filesystem that is to be accessed." +"The exclusive ordered comparisons ``>`` and ``<`` are similar to the " +"inclusive ordered comparisons in that they rely on the relative position of " +"the candidate version and the specified version given the consistent " +"ordering defined by the standard `Version scheme`_. However, they " +"specifically exclude pre-releases, post-releases, and local versions of the " +"specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:1163 +#: ../source/specifications/version-specifiers.rst:988 msgid "" -"On the various \\*nix operating systems the only allowed values for " -"```` is for it to be omitted, ``localhost``, or another FQDN that the " -"current machine believes matches its own host. In other words, on \\*nix the " -"``file://`` scheme can only be used to access paths on the local machine." +"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 " +"that releases are later than a particular post release, including additional " +"post releases, by using ``>V.postN``. For example, ``>1.7`` will allow " +"``1.7.1`` but not ``1.7.0.post1`` and ``>1.7.post2`` will allow ``1.7.1`` " +"and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:1168 +#: ../source/specifications/version-specifiers.rst:995 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 " -"on Windows the ```` parameter may be used to specify a file residing " -"on a network share. In other words, in order to translate ``\\" -"\\machine\\volume\\file`` to a ``file://`` url, it would end up as ``file://" -"machine/volume/file``. For more information on ``file://`` URLs on Windows " -"see `MSDN `_." +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:1179 -msgid "Summary of differences from pkg_resources.parse_version" +#: ../source/specifications/version-specifiers.rst:998 +msgid "" +"The exclusive ordered comparison ```_ project):" +"Pre-releases of any kind, including developmental releases, are implicitly " +"excluded from all version specifiers, *unless* they are already present on " +"the system, explicitly requested by the user, or if the only available " +"version that satisfies the version specifier is a pre-release." msgstr "" -#: ../source/specifications/version-specifiers.rst:1266 -msgid "August 2014: This specification was approved through :pep:`440`." +#: ../source/specifications/version-specifiers.rst:1041 +msgid "By default, dependency resolution tools SHOULD:" msgstr "" -#: ../source/specifications/virtual-environments.rst:6 -#, fuzzy -msgid "Python Virtual Environments" -msgstr "Entorno virtual" +#: ../source/specifications/version-specifiers.rst:1043 +msgid "accept already installed pre-releases for all version specifiers" +msgstr "" -#: ../source/specifications/virtual-environments.rst:8 +#: ../source/specifications/version-specifiers.rst:1044 msgid "" -"For Python 3.3 and later versions, :pep:`405` introduced interpreter level " -"support for the concept of \"Python Virtual Environments\". Each virtual " -"environment has its own Python binary (allowing creation of environments " -"with various Python versions) and can have its own independent set of " -"installed Python packages in its site directories, but shares the standard " -"library with the base installed Python. While the concept of virtual " -"environments existed prior to this update, there was no previously " -"standardised mechanism for declaring or discovering them." +"accept remotely available pre-releases for version specifiers where there is " +"no final or post release that satisfies the version specifier" msgstr "" -#: ../source/specifications/virtual-environments.rst:18 -#, fuzzy -msgid "Runtime detection of virtual environments" -msgstr "Facultativamente, cree un entorno virtual" +#: ../source/specifications/version-specifiers.rst:1046 +msgid "exclude all other pre-releases from consideration" +msgstr "" -#: ../source/specifications/virtual-environments.rst:20 +#: ../source/specifications/version-specifiers.rst:1048 msgid "" -"At runtime, virtual environments can be identified by virtue of :py:data:" -"`sys.prefix` (the filesystem location of the running interpreter) having a " -"different value from :py:data:`sys.base_prefix` (the default filesystem " -"location of the standard library directories)." +"Dependency resolution tools MAY issue a warning if a pre-release is needed " +"to satisfy a version specifier." msgstr "" -#: ../source/specifications/virtual-environments.rst:25 -msgid "" -":ref:`venv-explanation` in the Python standard library documentation for " -"the :py:mod:`venv` module covers this along with the concept of " -"\"activating\" a virtual environment in an interactive operating system " -"shell (this activation step is optional and hence the changes it makes can't " -"be reliably used to detect whether a Python program is running in a virtual " -"environment or not)." +#: ../source/specifications/version-specifiers.rst:1051 +msgid "" +"Dependency resolution tools SHOULD also allow users to request the following " +"alternative behaviours:" msgstr "" -#: ../source/specifications/virtual-environments.rst:33 -msgid "Declaring installation environments as Python virtual environments" +#: ../source/specifications/version-specifiers.rst:1054 +msgid "accepting pre-releases for all version specifiers" msgstr "" -#: ../source/specifications/virtual-environments.rst:35 +#: ../source/specifications/version-specifiers.rst:1055 msgid "" -"As described in :pep:`405`, a Python virtual environment in its simplest " -"form consists of nothing more than a copy or symlink of the Python binary " -"accompanied by a ``site-packages`` directory and a ``pyvenv.cfg`` file with " -"a ``home`` key that indicates where to find the Python standard library " -"modules." +"excluding pre-releases for all version specifiers (reporting an error or " +"warning if a pre-release is already installed locally, or if a pre-release " +"is the only way to satisfy a particular specifier)" msgstr "" -#: ../source/specifications/virtual-environments.rst:40 +#: ../source/specifications/version-specifiers.rst:1059 msgid "" -"While designed to meet the needs of the standard :py:mod:`venv` module, this " -"split installation and ``pyvenv.cfg`` file approach can be used by *any* " -"Python installation provider that desires Python-specific tools to be aware " -"that they are already operating in a virtual environment and no further " -"environment nesting is required or desired." +"Dependency resolution tools MAY also allow the above behaviour to be " +"controlled on a per-distribution basis." msgstr "" -#: ../source/specifications/virtual-environments.rst:46 +#: ../source/specifications/version-specifiers.rst:1062 msgid "" -"Even in the absence of a ``pyvenv.cfg`` file, any approach (e.g. " -"``sitecustomize.py``, patching the installed Python runtime) that results " -"in :py:data:`sys.prefix` and :py:data:`sys.base_prefix` having different " -"values, while still providing a matching default package installation scheme " -"in :py:mod:`sysconfig`, will be detected and behave as a Python virtual " -"environment." +"Post-releases and final releases receive no special treatment in version " +"specifiers - they are always included unless explicitly excluded." msgstr "" -#: ../source/specifications/virtual-environments.rst:56 -msgid "May 2012: This specification was approved through :pep:`405`." +#: ../source/specifications/version-specifiers.rst:1069 +msgid "``~=3.1``: version 3.1 or later, but not version 4.0 or later." msgstr "" -#: ../source/support.rst:3 -msgid "How to Get Support" -msgstr "Cómo obtener asistencia" +#: ../source/specifications/version-specifiers.rst:1070 +msgid "``~=3.1.2``: version 3.1.2 or later, but not version 3.2.0 or later." +msgstr "" -#: ../source/support.rst:5 -msgid "" -"For support related to a specific project, see the links on the :doc:" -"`Projects ` page." +#: ../source/specifications/version-specifiers.rst:1071 +msgid "``~=3.1a1``: version 3.1a1 or later, but not version 4.0 or later." msgstr "" -#: ../source/support.rst:8 +#: ../source/specifications/version-specifiers.rst:1072 msgid "" -"For something more general, or when you're just not sure, please `open an " -"issue `_ on the `packaging-problems `_ repository on GitHub." +"``== 3.1``: specifically version 3.1 (or 3.1.0), excludes all pre-releases, " +"post releases, developmental releases and any 3.1.x maintenance releases." msgstr "" -#: ../source/tutorials/creating-documentation.rst:4 -#, fuzzy -msgid "Creating documentation" -msgstr "Creación de documentación" - -#: ../source/tutorials/creating-documentation.rst:6 +#: ../source/specifications/version-specifiers.rst:1074 msgid "" -"This tutorial has been removed since it is not related to packaging and was " -"unmaintained. Please see the `Sphinx tutorial `_ instead." +"``== 3.1.*``: any version that starts with 3.1. Equivalent to the " +"``~=3.1.0`` compatible release clause." msgstr "" -#: ../source/tutorials/index.rst:4 +#: ../source/specifications/version-specifiers.rst:1076 msgid "" -"**Tutorials** are opinionated step-by-step guides to help you get familiar " -"with packaging concepts. For more detailed information on specific packaging " -"topics, see :doc:`/guides/index`." +"``~=3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3 and not " +"version 3.2.0 or later." msgstr "" -#: ../source/tutorials/installing-packages.rst:5 -msgid "Installing Packages" -msgstr "Instalación de paquetes" +#: ../source/specifications/version-specifiers.rst:1081 +msgid "Direct references" +msgstr "" -#: ../source/tutorials/installing-packages.rst:7 +#: ../source/specifications/version-specifiers.rst:1083 msgid "" -"This section covers the basics of how to install Python :term:`packages " -"`." +"Some automated tools may permit the use of a direct reference as an " +"alternative to a normal version specifier. A direct reference consists of " +"the specifier ``@`` and an explicit URL." msgstr "" -#: ../source/tutorials/installing-packages.rst:10 +#: ../source/specifications/version-specifiers.rst:1087 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 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." +"Whether or not direct references are appropriate depends on the specific use " +"case for the version specifier. Automated tools SHOULD at least issue " +"warnings and MAY reject them entirely when direct references are used " +"inappropriately." msgstr "" -#: ../source/tutorials/installing-packages.rst:24 -msgid "Requirements for Installing Packages" -msgstr "Requisitos para instalar paquetes" +#: ../source/specifications/version-specifiers.rst:1092 +msgid "" +"Public index servers SHOULD NOT allow the use of direct references in " +"uploaded distributions. Direct references are intended as a tool for " +"software integrators rather than publishers." +msgstr "" -#: ../source/tutorials/installing-packages.rst:26 +#: ../source/specifications/version-specifiers.rst:1096 msgid "" -"This section describes the steps to follow before installing other Python " -"packages." +"Depending on the use case, some appropriate targets for a direct URL " +"reference may be an sdist or a wheel binary archive. The exact URLs and " +"targets supported will be tool dependent." msgstr "" -"Esta sección describe los pasos que hay que seguir antes de instalar otros " -"paquetes de Python." -#: ../source/tutorials/installing-packages.rst:31 -msgid "Ensure you can run Python from the command line" -msgstr "Cerciórese de que pueda ejecutar Python desde la línea de órdenes" +#: ../source/specifications/version-specifiers.rst:1100 +msgid "For example, a local source archive may be referenced directly::" +msgstr "" -#: ../source/tutorials/installing-packages.rst:33 -msgid "" -"Before you go any further, make sure you have Python and that the expected " -"version is available from your command line. You can check this by running:" +#: ../source/specifications/version-specifiers.rst:1104 +msgid "Alternatively, a prebuilt archive may also be referenced::" msgstr "" -#: ../source/tutorials/installing-packages.rst:49 +#: ../source/specifications/version-specifiers.rst:1108 msgid "" -"You should get some output like ``Python 3.6.3``. If you do not have Python, " -"please install the latest 3.x version from `python.org`_ or refer to the :" -"ref:`Installing Python ` section of the " -"Hitchhiker's Guide to Python." +"All direct references that do not refer to a local file URL SHOULD specify a " +"secure transport mechanism (such as ``https``) AND include an expected hash " +"value in the URL for verification purposes. If a direct reference is " +"specified without any hash information, with hash information that the tool " +"doesn't understand, or with a selected hash algorithm that the tool " +"considers too weak to trust, automated tools SHOULD at least emit a warning " +"and MAY refuse to rely on the URL. If such a direct reference also uses an " +"insecure transport, automated tools SHOULD NOT rely on the URL." msgstr "" -#: ../source/tutorials/installing-packages.rst:53 -msgid "If you're a newcomer and you get an error like this:" +#: ../source/specifications/version-specifiers.rst:1117 +msgid "" +"It is RECOMMENDED that only hashes which are unconditionally provided by the " +"latest version of the standard library's :py:mod:`hashlib` module be used " +"for source archive hashes. At time of writing, that list consists of " +"``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and " +"``'sha512'``." msgstr "" -#: ../source/tutorials/installing-packages.rst:62 +#: ../source/specifications/version-specifiers.rst:1123 msgid "" -"It's because this command and other suggested commands in this tutorial are " -"intended to be run in a *shell* (also called a *terminal* or *console*). See " -"the Python for Beginners `getting started tutorial`_ for an introduction to " -"using your operating system's shell and interacting with Python." +"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/tutorials/installing-packages.rst:68 +#: ../source/specifications/version-specifiers.rst:1127 msgid "" -"If you're using an enhanced shell like IPython or the Jupyter notebook, you " -"can run system commands like those in this tutorial by prefacing them with a " -"``!`` character:" +"For version control references, the ``VCS+protocol`` scheme SHOULD be used " +"to identify both the version control system and the secure transport, and a " +"version control system with hash based commit identifiers SHOULD be used. " +"Automated tools MAY omit warnings about missing hashes for version control " +"systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/tutorials/installing-packages.rst:78 +#: ../source/specifications/version-specifiers.rst:1133 msgid "" -"It's recommended to write ``{sys.executable}`` rather than plain ``python`` " -"in order to ensure that commands are run in the Python installation matching " -"the currently running notebook (which may not be the same Python " -"installation that the ``python`` command refers to)." +"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 " +"end of the URL using the ``@`` or the ``@#`` " +"notation." msgstr "" -#: ../source/tutorials/installing-packages.rst:83 +#: ../source/specifications/version-specifiers.rst:1140 msgid "" -"Due to the way most Linux distributions are handling the Python 3 migration, " -"Linux users using the system Python without creating a virtual environment " -"first should replace the ``python`` command in this tutorial with " -"``python3`` and the ``python -m pip`` command with ``python3 -m pip --" -"user``. Do *not* run any of the commands in this tutorial with ``sudo``: if " -"you get a permissions error, come back to the section on creating virtual " -"environments, set one up, and then continue with the tutorial as written." +"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 " +"embedded as part of the URL. Secondly, the commit hash is included even when " +"retrieving based on a tag, in order to meet the requirement above that " +"*every* link should include a hash to make things harder to forge (creating " +"a malicious repo with a particular tag is easy, creating one with a specific " +"*hash*, less so)." msgstr "" -#: ../source/tutorials/installing-packages.rst:95 -msgid "Ensure you can run pip from the command line" -msgstr "Cerciórese de que pueda ejecutar pip desde la línea de órdenes" +#: ../source/specifications/version-specifiers.rst:1148 +#, fuzzy +msgid "Remote URL examples::" +msgstr "Por ejemplo::" -#: ../source/tutorials/installing-packages.rst:97 +#: ../source/specifications/version-specifiers.rst:1156 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1158 msgid "" -"Additionally, you'll need to make sure you have :ref:`pip` available. You " -"can check this by running:" +"File URLs take the form of ``file:///``. If the ```` is " +"omitted it is assumed to be ``localhost`` and even if the ```` is " +"omitted the third slash MUST still exist. The ```` defines what the " +"file path on the filesystem that is to be accessed." msgstr "" -#: ../source/tutorials/installing-packages.rst:112 +#: ../source/specifications/version-specifiers.rst:1163 msgid "" -"If you installed Python from source, with an installer from `python.org`_, " -"or via `Homebrew`_ you should already have pip. If you're on Linux and " -"installed using your OS package manager, you may have to install pip " -"separately, see :doc:`/guides/installing-using-linux-tools`." +"On the various \\*nix operating systems the only allowed values for " +"```` is for it to be omitted, ``localhost``, or another FQDN that the " +"current machine believes matches its own host. In other words, on \\*nix the " +"``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/tutorials/installing-packages.rst:119 +#: ../source/specifications/version-specifiers.rst:1168 msgid "" -"If ``pip`` isn't already installed, then first try to bootstrap it from the " -"standard library:" +"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 " +"on Windows the ```` parameter may be used to specify a file residing " +"on a network share. In other words, in order to translate ``\\" +"\\machine\\volume\\file`` to a ``file://`` url, it would end up as ``file://" +"machine/volume/file``. For more information on ``file://`` URLs on Windows " +"see `MSDN `_." msgstr "" -#: ../source/tutorials/installing-packages.rst:134 -msgid "If that still doesn't allow you to run ``python -m pip``:" +#: ../source/specifications/version-specifiers.rst:1179 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1181 +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/tutorials/installing-packages.rst:136 +#: ../source/specifications/version-specifiers.rst:1185 msgid "" -"Securely Download `get-pip.py `_ [1]_" +"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/tutorials/installing-packages.rst:139 +#: ../source/specifications/version-specifiers.rst:1189 msgid "" -"Run ``python get-pip.py``. [2]_ This will install or upgrade pip. " -"Additionally, it will install :ref:`setuptools` and :ref:`wheel` if they're " -"not installed already." +"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/tutorials/installing-packages.rst:145 +#: ../source/specifications/version-specifiers.rst:1193 msgid "" -"Be cautious if you're using a Python install that's managed by your " -"operating system or another package manager. get-pip.py does not coordinate " -"with those tools, and may leave your system in an inconsistent state. You " -"can use ``python get-pip.py --prefix=/usr/local/`` to install in ``/usr/" -"local`` which is designed for locally-installed software." +"``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/tutorials/installing-packages.rst:154 -msgid "Ensure pip, setuptools, and wheel are up to date" +#: ../source/specifications/version-specifiers.rst:1202 +msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/tutorials/installing-packages.rst:156 +#: ../source/specifications/version-specifiers.rst:1204 msgid "" -"While ``pip`` alone is sufficient to install from pre-built binary archives, " -"up to date copies of the ``setuptools`` and ``wheel`` projects are useful to " -"ensure you can also install from source archives:" +"As noted earlier in the :ref:`public-version-identifiers` section, published " +"version identifiers SHOULD use the canonical format. This section provides " +"regular expressions that can be used to test whether a version is already in " +"that form, and if it's not, extract the various components for subsequent " +"normalization." msgstr "" -#: ../source/tutorials/installing-packages.rst:173 -msgid "Optionally, create a virtual environment" -msgstr "Facultativamente, cree un entorno virtual" - -#: ../source/tutorials/installing-packages.rst:175 +#: ../source/specifications/version-specifiers.rst:1210 msgid "" -"See :ref:`section below ` for " -"details, but here's the basic :doc:`venv ` [3]_ command " -"to use on a typical Linux system:" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" msgstr "" -#: ../source/tutorials/installing-packages.rst:192 +#: ../source/specifications/version-specifiers.rst:1219 msgid "" -"This will create a new virtual environment in the ``tutorial_env`` " -"subdirectory, and configure the current shell to use it as the default " -"``python`` environment." +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" msgstr "" -#: ../source/tutorials/installing-packages.rst:199 -msgid "Creating Virtual Environments" +#: ../source/specifications/version-specifiers.rst:1266 +msgid "August 2014: This specification was approved through :pep:`440`." msgstr "" -#: ../source/tutorials/installing-packages.rst:201 -msgid "" -"Python \"Virtual Environments\" allow Python :term:`packages ` to be installed in an isolated location for a particular " -"application, rather than being installed globally. If you are looking to " -"safely install global command line tools, see :doc:`/guides/installing-stand-" -"alone-command-line-tools`." -msgstr "" +#: ../source/specifications/virtual-environments.rst:6 +#, fuzzy +msgid "Python Virtual Environments" +msgstr "Entorno virtual" -#: ../source/tutorials/installing-packages.rst:207 +#: ../source/specifications/virtual-environments.rst:8 msgid "" -"Imagine you have an application that needs version 1 of LibFoo, but another " -"application requires version 2. How can you use both these applications? If " -"you install everything into /usr/lib/python3.6/site-packages (or whatever " -"your platform’s standard location is), it’s easy to end up in a situation " -"where you unintentionally upgrade an application that shouldn’t be upgraded." +"For Python 3.3 and later versions, :pep:`405` introduced interpreter level " +"support for the concept of \"Python Virtual Environments\". Each virtual " +"environment has its own Python binary (allowing creation of environments " +"with various Python versions) and can have its own independent set of " +"installed Python packages in its site directories, but shares the standard " +"library with the base installed Python. While the concept of virtual " +"environments existed prior to this update, there was no previously " +"standardised mechanism for declaring or discovering them." msgstr "" -#: ../source/tutorials/installing-packages.rst:213 -msgid "" -"Or more generally, what if you want to install an application and leave it " -"be? If an application works, any change in its libraries or the versions of " -"those libraries can break the application." -msgstr "" +#: ../source/specifications/virtual-environments.rst:18 +#, fuzzy +msgid "Runtime detection of virtual environments" +msgstr "Facultativamente, cree un entorno virtual" -#: ../source/tutorials/installing-packages.rst:217 +#: ../source/specifications/virtual-environments.rst:20 msgid "" -"Also, what if you can’t install :term:`packages ` into " -"the global site-packages directory? For instance, on a shared host." +"At runtime, virtual environments can be identified by virtue of :py:data:" +"`sys.prefix` (the filesystem location of the running interpreter) having a " +"different value from :py:data:`sys.base_prefix` (the default filesystem " +"location of the standard library directories)." msgstr "" -#: ../source/tutorials/installing-packages.rst:220 +#: ../source/specifications/virtual-environments.rst:25 msgid "" -"In all these cases, virtual environments can help you. They have their own " -"installation directories and they don’t share libraries with other virtual " -"environments." +":ref:`venv-explanation` in the Python standard library documentation for " +"the :py:mod:`venv` module covers this along with the concept of " +"\"activating\" a virtual environment in an interactive operating system " +"shell (this activation step is optional and hence the changes it makes can't " +"be reliably used to detect whether a Python program is running in a virtual " +"environment or not)." msgstr "" -#: ../source/tutorials/installing-packages.rst:224 -msgid "" -"Currently, there are two common tools for creating Python virtual " -"environments:" +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" msgstr "" -#: ../source/tutorials/installing-packages.rst:226 +#: ../source/specifications/virtual-environments.rst:35 msgid "" -":doc:`venv ` is available by default in Python 3.3 and " -"later, and installs :ref:`pip` and :ref:`setuptools` into created virtual " -"environments in Python 3.4 and later." +"As described in :pep:`405`, a Python virtual environment in its simplest " +"form consists of nothing more than a copy or symlink of the Python binary " +"accompanied by a ``site-packages`` directory and a ``pyvenv.cfg`` file with " +"a ``home`` key that indicates where to find the Python standard library " +"modules." msgstr "" -#: ../source/tutorials/installing-packages.rst:229 +#: ../source/specifications/virtual-environments.rst:40 msgid "" -":ref:`virtualenv` needs to be installed separately, but supports Python 2.7+ " -"and Python 3.3+, and :ref:`pip`, :ref:`setuptools` and :ref:`wheel` are " -"always installed into created virtual environments by default (regardless of " -"Python version)." +"While designed to meet the needs of the standard :py:mod:`venv` module, this " +"split installation and ``pyvenv.cfg`` file approach can be used by *any* " +"Python installation provider that desires Python-specific tools to be aware " +"that they are already operating in a virtual environment and no further " +"environment nesting is required or desired." msgstr "" -#: ../source/tutorials/installing-packages.rst:234 -msgid "The basic usage is like so:" +#: ../source/specifications/virtual-environments.rst:46 +msgid "" +"Even in the absence of a ``pyvenv.cfg`` file, any approach (e.g. " +"``sitecustomize.py``, patching the installed Python runtime) that results " +"in :py:data:`sys.prefix` and :py:data:`sys.base_prefix` having different " +"values, while still providing a matching default package installation scheme " +"in :py:mod:`sysconfig`, will be detected and behave as a Python virtual " +"environment." msgstr "" -#: ../source/tutorials/installing-packages.rst:236 -msgid "Using :doc:`venv `:" +#: ../source/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." msgstr "" -#: ../source/tutorials/installing-packages.rst:252 -msgid "Using :ref:`virtualenv`:" -msgstr "" +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "Cómo obtener asistencia" -#: ../source/tutorials/installing-packages.rst:268 +#: ../source/support.rst:5 msgid "" -"For more information, see the :doc:`venv ` docs or the :" -"doc:`virtualenv ` docs." +"For support related to a specific project, see the links on the :doc:" +"`Projects ` page." msgstr "" -#: ../source/tutorials/installing-packages.rst:271 +#: ../source/support.rst:8 msgid "" -"The use of :command:`source` under Unix shells ensures that the virtual " -"environment's variables are set within the current shell, and not in a " -"subprocess (which then disappears, having no useful effect)." +"For something more general, or when you're just not sure, please `open an " +"issue `_ on the `packaging-problems `_ repository on GitHub." msgstr "" -#: ../source/tutorials/installing-packages.rst:276 -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:" -msgstr "" +#: ../source/tutorials/creating-documentation.rst:4 +#, fuzzy +msgid "Creating documentation" +msgstr "Creación de documentación" -#: ../source/tutorials/installing-packages.rst:286 +#: ../source/tutorials/creating-documentation.rst:6 msgid "" -"Managing multiple virtual environments directly can become tedious, so the :" -"ref:`dependency management tutorial ` introduces a " -"higher level tool, :ref:`Pipenv`, that automatically manages a separate " -"virtual environment for each project and application that you work on." -msgstr "" - -#: ../source/tutorials/installing-packages.rst:293 -msgid "Use pip for Installing" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." msgstr "" -#: ../source/tutorials/installing-packages.rst:295 +#: ../source/tutorials/index.rst:4 msgid "" -":ref:`pip` is the recommended installer. Below, we'll cover the most common " -"usage scenarios. For more detail, see the :doc:`pip docs `, which " -"includes a complete :doc:`Reference Guide `." +"**Tutorials** are opinionated step-by-step guides to help you get familiar " +"with packaging concepts. For more detailed information on specific packaging " +"topics, see :doc:`/guides/index`." msgstr "" -#: ../source/tutorials/installing-packages.rst:301 -msgid "Installing from PyPI" -msgstr "Instalación a partir de PyPI" +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "Instalación de paquetes" -#: ../source/tutorials/installing-packages.rst:303 +#: ../source/tutorials/installing-packages.rst:7 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 `. A full description of the " -"supported specifiers can be found in the :ref:`Version specifier " -"specification `. Below are some examples." +"This section covers the basics of how to install Python :term:`packages " +"`." msgstr "" -#: ../source/tutorials/installing-packages.rst:311 -msgid "To install the latest version of \"SomeProject\":" +#: ../source/tutorials/installing-packages.rst:10 +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 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." msgstr "" -#: ../source/tutorials/installing-packages.rst:325 -msgid "To install a specific version:" -msgstr "Para instalar una versión específica:" +#: ../source/tutorials/installing-packages.rst:24 +msgid "Requirements for Installing Packages" +msgstr "Requisitos para instalar paquetes" -#: ../source/tutorials/installing-packages.rst:339 -msgid "To install greater than or equal to one version and less than another:" +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." msgstr "" +"Esta sección describe los pasos que hay que seguir antes de instalar otros " +"paquetes de Python." + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +msgstr "Cerciórese de que pueda ejecutar Python desde la línea de órdenes" -#: ../source/tutorials/installing-packages.rst:354 +#: ../source/tutorials/installing-packages.rst:33 msgid "" -"To install a version that's :ref:`compatible ` with a certain version: [4]_" +"Before you go any further, make sure you have Python and that the expected " +"version is available from your command line. You can check this by running:" msgstr "" -#: ../source/tutorials/installing-packages.rst:369 +#: ../source/tutorials/installing-packages.rst:49 msgid "" -"In this case, this means to install any version \"==1.4.*\" version that's " -"also \">=1.4.2\"." +"You should get some output like ``Python 3.6.3``. If you do not have Python, " +"please install the latest 3.x version from `python.org`_ or refer to the :" +"ref:`Installing Python ` section of the " +"Hitchhiker's Guide to Python." msgstr "" -#: ../source/tutorials/installing-packages.rst:374 -msgid "Source Distributions vs Wheels" +#: ../source/tutorials/installing-packages.rst:53 +msgid "If you're a newcomer and you get an error like this:" msgstr "" -#: ../source/tutorials/installing-packages.rst:376 +#: ../source/tutorials/installing-packages.rst:62 msgid "" -":ref:`pip` can install from either :term:`Source Distributions (sdist) " -"` or :term:`Wheels `, but if both " -"are present on PyPI, pip will prefer a compatible :term:`wheel `. You " -"can override pip`s default behavior by e.g. using its :ref:`--no-binary ` option." +"It's because this command and other suggested commands in this tutorial are " +"intended to be run in a *shell* (also called a *terminal* or *console*). See " +"the Python for Beginners `getting started tutorial`_ for an introduction to " +"using your operating system's shell and interacting with Python." msgstr "" -#: ../source/tutorials/installing-packages.rst:382 +#: ../source/tutorials/installing-packages.rst:68 msgid "" -":term:`Wheels ` are a pre-built :term:`distribution ` format that provides faster installation compared to :term:`Source " -"Distributions (sdist) `, especially when " -"a project contains compiled extensions." +"If you're using an enhanced shell like IPython or the Jupyter notebook, you " +"can run system commands like those in this tutorial by prefacing them with a " +"``!`` character:" msgstr "" -#: ../source/tutorials/installing-packages.rst:387 +#: ../source/tutorials/installing-packages.rst:78 msgid "" -"If :ref:`pip` does not find a wheel to install, it will locally build a " -"wheel and cache it for future installs, instead of rebuilding the source " -"distribution in the future." +"It's recommended to write ``{sys.executable}`` rather than plain ``python`` " +"in order to ensure that commands are run in the Python installation matching " +"the currently running notebook (which may not be the same Python " +"installation that the ``python`` command refers to)." msgstr "" -#: ../source/tutorials/installing-packages.rst:395 -msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +#: ../source/tutorials/installing-packages.rst:83 +msgid "" +"Due to the way most Linux distributions are handling the Python 3 migration, " +"Linux users using the system Python without creating a virtual environment " +"first should replace the ``python`` command in this tutorial with " +"``python3`` and the ``python -m pip`` command with ``python3 -m pip --" +"user``. Do *not* run any of the commands in this tutorial with ``sudo``: if " +"you get a permissions error, come back to the section on creating virtual " +"environments, set one up, and then continue with the tutorial as written." msgstr "" -#: ../source/tutorials/installing-packages.rst:412 -msgid "Installing to the User Site" -msgstr "" +#: ../source/tutorials/installing-packages.rst:95 +msgid "Ensure you can run pip from the command line" +msgstr "Cerciórese de que pueda ejecutar pip desde la línea de órdenes" -#: ../source/tutorials/installing-packages.rst:414 +#: ../source/tutorials/installing-packages.rst:97 msgid "" -"To install :term:`packages ` that are isolated to the " -"current user, use the ``--user`` flag:" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" msgstr "" -#: ../source/tutorials/installing-packages.rst:429 +#: ../source/tutorials/installing-packages.rst:112 msgid "" -"For more information see the `User Installs `_ section from the pip docs." +"If you installed Python from source, with an installer from `python.org`_, " +"or via `Homebrew`_ you should already have pip. If you're on Linux and " +"installed using your OS package manager, you may have to install pip " +"separately, see :doc:`/guides/installing-using-linux-tools`." msgstr "" -#: ../source/tutorials/installing-packages.rst:433 +#: ../source/tutorials/installing-packages.rst:119 msgid "" -"Note that the ``--user`` flag has no effect when inside a virtual " -"environment - all installation commands will affect the virtual environment." +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" msgstr "" -#: ../source/tutorials/installing-packages.rst:436 -msgid "" -"If ``SomeProject`` defines any command-line scripts or console entry points, " -"``--user`` will cause them to be installed inside the `user base`_'s binary " -"directory, which may or may not already be present in your shell's :envvar:" -"`PATH`. (Starting in version 10, pip displays a warning when installing any " -"scripts to a directory outside :envvar:`PATH`.) If the scripts are not " -"available in your shell after installation, you'll need to add the directory " -"to your :envvar:`PATH`:" +#: ../source/tutorials/installing-packages.rst:134 +msgid "If that still doesn't allow you to run ``python -m pip``:" msgstr "" -#: ../source/tutorials/installing-packages.rst:444 +#: ../source/tutorials/installing-packages.rst:136 msgid "" -"On Linux and macOS you can find the user base binary directory by running " -"``python -m site --user-base`` and adding ``bin`` to the end. For example, " -"this will typically print ``~/.local`` (with ``~`` expanded to the absolute " -"path to your home directory) so you'll need to add ``~/.local/bin`` to your " -"``PATH``. You can set your ``PATH`` permanently by `modifying ~/.profile`_." +"Securely Download `get-pip.py `_ [1]_" msgstr "" -#: ../source/tutorials/installing-packages.rst:450 +#: ../source/tutorials/installing-packages.rst:139 msgid "" -"On Windows you can find the user base binary directory by running ``py -m " -"site --user-site`` and replacing ``site-packages`` with ``Scripts``. For " -"example, this could return ``C:" -"\\Users\\Username\\AppData\\Roaming\\Python36\\site-packages`` so you would " -"need to set your ``PATH`` to include ``C:" -"\\Users\\Username\\AppData\\Roaming\\Python36\\Scripts``. You can set your " -"user ``PATH`` permanently in the `Control Panel`_. You may need to log out " -"for the ``PATH`` changes to take effect." +"Run ``python get-pip.py``. [2]_ This will install or upgrade pip. " +"Additionally, it will install :ref:`setuptools` and :ref:`wheel` if they're " +"not installed already." msgstr "" -#: ../source/tutorials/installing-packages.rst:466 +#: ../source/tutorials/installing-packages.rst:145 msgid "" -"Install a list of requirements specified in a :ref:`Requirements File `." +"Be cautious if you're using a Python install that's managed by your " +"operating system or another package manager. get-pip.py does not coordinate " +"with those tools, and may leave your system in an inconsistent state. You " +"can use ``python get-pip.py --prefix=/usr/local/`` to install in ``/usr/" +"local`` which is designed for locally-installed software." msgstr "" -#: ../source/tutorials/installing-packages.rst:482 -msgid "Installing from VCS" -msgstr "Instalación a partir de un sistema de control de versiones" - -#: ../source/tutorials/installing-packages.rst:484 -msgid "" -"Install a project from VCS in \"editable\" mode. For a full breakdown of " -"the syntax, see pip's section on :ref:`VCS Support `." +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" msgstr "" -#: ../source/tutorials/installing-packages.rst:506 -msgid "Installing from other Indexes" -msgstr "Instalación a partir de otros índices" - -#: ../source/tutorials/installing-packages.rst:508 -msgid "Install from an alternate index" -msgstr "Instalación a partir de un índice alternativo" - -#: ../source/tutorials/installing-packages.rst:522 +#: ../source/tutorials/installing-packages.rst:156 msgid "" -"Search an additional index during install, in addition to :term:`PyPI " -"`" +"While ``pip`` alone is sufficient to install from pre-built binary archives, " +"up to date copies of the ``setuptools`` and ``wheel`` projects are useful to " +"ensure you can also install from source archives:" msgstr "" -#: ../source/tutorials/installing-packages.rst:538 -msgid "Installing from a local src tree" -msgstr "" +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "Facultativamente, cree un entorno virtual" -#: ../source/tutorials/installing-packages.rst:541 +#: ../source/tutorials/installing-packages.rst:175 msgid "" -"Installing from local src in :doc:`Development Mode `, i.e. in such a way that the project appears to be " -"installed, but yet is still editable from the src tree." +"See :ref:`section below ` for " +"details, but here's the basic :doc:`venv ` [3]_ command " +"to use on a typical Linux system:" msgstr "" -#: ../source/tutorials/installing-packages.rst:558 -msgid "You can also install normally from src" +#: ../source/tutorials/installing-packages.rst:192 +msgid "" +"This will create a new virtual environment in the ``tutorial_env`` " +"subdirectory, and configure the current shell to use it as the default " +"``python`` environment." msgstr "" -#: ../source/tutorials/installing-packages.rst:573 -msgid "Installing from local archives" +#: ../source/tutorials/installing-packages.rst:199 +msgid "Creating Virtual Environments" msgstr "" -#: ../source/tutorials/installing-packages.rst:575 -msgid "Install a particular source archive file." +#: ../source/tutorials/installing-packages.rst:201 +msgid "" +"Python \"Virtual Environments\" allow Python :term:`packages ` to be installed in an isolated location for a particular " +"application, rather than being installed globally. If you are looking to " +"safely install global command line tools, see :doc:`/guides/installing-stand-" +"alone-command-line-tools`." msgstr "" -#: ../source/tutorials/installing-packages.rst:589 +#: ../source/tutorials/installing-packages.rst:207 msgid "" -"Install from a local directory containing archives (and don't check :term:" -"`PyPI `)" +"Imagine you have an application that needs version 1 of LibFoo, but another " +"application requires version 2. How can you use both these applications? If " +"you install everything into /usr/lib/python3.6/site-packages (or whatever " +"your platform’s standard location is), it’s easy to end up in a situation " +"where you unintentionally upgrade an application that shouldn’t be upgraded." msgstr "" -#: ../source/tutorials/installing-packages.rst:609 -msgid "Installing from other sources" -msgstr "Instalación a partir de otras fuentes" - -#: ../source/tutorials/installing-packages.rst:611 +#: ../source/tutorials/installing-packages.rst:213 msgid "" -"To install from other data sources (for example Amazon S3 storage) you can " -"create a helper application that presents the data in a format compliant " -"with the :ref:`simple repository API `:, and use the " -"``--extra-index-url`` flag to direct pip to use that index." +"Or more generally, what if you want to install an application and leave it " +"be? If an application works, any change in its libraries or the versions of " +"those libraries can break the application." msgstr "" -#: ../source/tutorials/installing-packages.rst:623 -msgid "Installing Prereleases" +#: ../source/tutorials/installing-packages.rst:217 +msgid "" +"Also, what if you can’t install :term:`packages ` into " +"the global site-packages directory? For instance, on a shared host." msgstr "" -#: ../source/tutorials/installing-packages.rst:625 +#: ../source/tutorials/installing-packages.rst:220 msgid "" -"Find pre-release and development versions, in addition to stable versions. " -"By default, pip only finds stable versions." +"In all these cases, virtual environments can help you. They have their own " +"installation directories and they don’t share libraries with other virtual " +"environments." msgstr "" -#: ../source/tutorials/installing-packages.rst:641 -msgid "Installing \"Extras\"" -msgstr "Instalando \"Extras\"" - -#: ../source/tutorials/installing-packages.rst:643 +#: ../source/tutorials/installing-packages.rst:224 msgid "" -"Extras are optional \"variants\" of a package, which may include additional " -"dependencies, and thereby enable additional functionality from the package. " -"If you wish to install an extra for a package which you know publishes one, " -"you can include it in the pip installation command:" +"Currently, there are two common tools for creating Python virtual " +"environments:" msgstr "" -#: ../source/tutorials/installing-packages.rst:666 +#: ../source/tutorials/installing-packages.rst:226 msgid "" -"\"Secure\" in this context means using a modern browser or a tool like :" -"command:`curl` that verifies SSL certificates when downloading from https " -"URLs." +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` and :ref:`setuptools` into created virtual " +"environments in Python 3.4 and later." msgstr "" -#: ../source/tutorials/installing-packages.rst:675 +#: ../source/tutorials/installing-packages.rst:229 msgid "" -"Beginning with Python 3.4, ``venv`` (a stdlib alternative to :ref:" -"`virtualenv`) will create virtualenv environments with ``pip`` pre-" -"installed, thereby making it an equal alternative to :ref:`virtualenv`." +":ref:`virtualenv` needs to be installed separately, but supports Python 2.7+ " +"and Python 3.3+, and :ref:`pip`, :ref:`setuptools` and :ref:`wheel` are " +"always installed into created virtual environments by default (regardless of " +"Python version)." msgstr "" -#: ../source/tutorials/installing-packages.rst:680 -msgid "" -"The compatible release specifier was accepted in :pep:`440` and support was " -"released in :ref:`setuptools` v8.0 and :ref:`pip` v6.0" +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" msgstr "" -#: ../source/tutorials/managing-dependencies.rst:4 -msgid "Managing Application Dependencies" -msgstr "Gestión de las dependencias de aplicación" - -#: ../source/tutorials/managing-dependencies.rst:6 -msgid "" -"The :ref:`package installation tutorial ` covered the " -"basics of getting set up to install and update Python packages." +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" msgstr "" -#: ../source/tutorials/managing-dependencies.rst:9 -msgid "" -"However, running these commands interactively can get tedious even for your " -"own personal projects, and things get even more difficult when trying to set " -"up development environments automatically for projects with multiple " -"contributors." +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" msgstr "" -#: ../source/tutorials/managing-dependencies.rst:13 +#: ../source/tutorials/installing-packages.rst:268 msgid "" -"This tutorial walks you through the use of :ref:`Pipenv` to manage " -"dependencies for an application. It will show you how to install and use the " -"necessary tools and make strong recommendations on best practices." +"For more information, see the :doc:`venv ` docs or the :" +"doc:`virtualenv ` docs." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:17 +#: ../source/tutorials/installing-packages.rst:271 msgid "" -"Keep in mind that Python is used for a great many different purposes, and " -"precisely how you want to manage your dependencies may change based on how " -"you decide to publish your software. The guidance presented here is most " -"directly applicable to the development and deployment of network services " -"(including web applications), but is also very well suited to managing " -"development and testing environments for any kind of project." +"The use of :command:`source` under Unix shells ensures that the virtual " +"environment's variables are set within the current shell, and not in a " +"subprocess (which then disappears, having no useful effect)." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:24 +#: ../source/tutorials/installing-packages.rst:276 msgid "" -"For alternatives, see `Other Tools for Application Dependency Management`_." +"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:" msgstr "" -"Para alternativas, mira `Other Tools for Application Dependency Management`_." - -#: ../source/tutorials/managing-dependencies.rst:27 -msgid "Installing Pipenv" -msgstr "Instalación de Pipenv" -#: ../source/tutorials/managing-dependencies.rst:29 +#: ../source/tutorials/installing-packages.rst:286 msgid "" -":ref:`Pipenv` is a dependency manager for Python projects. If you're " -"familiar with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit " -"to those tools. While :ref:`pip` alone is often sufficient for personal use, " -"Pipenv is recommended for collaborative projects as it's a higher-level tool " -"that simplifies dependency management for common use cases." +"Managing multiple virtual environments directly can become tedious, so the :" +"ref:`dependency management tutorial ` introduces a " +"higher level tool, :ref:`Pipenv`, that automatically manages a separate " +"virtual environment for each project and application that you work on." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:35 -msgid "Use ``pip`` to install Pipenv:" +#: ../source/tutorials/installing-packages.rst:293 +msgid "Use pip for Installing" msgstr "" -#: ../source/tutorials/managing-dependencies.rst:51 +#: ../source/tutorials/installing-packages.rst:295 msgid "" -"This does a `user installation`_ to prevent breaking any system-wide " -"packages. If ``pipenv`` isn't available in your shell after installation, " -"you'll need to add the :py:data:`user base `'s binary " -"directory to your ``PATH``. See :ref:`Installing to the User Site` for more " -"information." +":ref:`pip` is the recommended installer. Below, we'll cover the most common " +"usage scenarios. For more detail, see the :doc:`pip docs `, which " +"includes a complete :doc:`Reference Guide `." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:62 -msgid "Installing packages for your project" -msgstr "Instalación de paquetes para su proyecto" +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "Instalación a partir de PyPI" -#: ../source/tutorials/managing-dependencies.rst:64 +#: ../source/tutorials/installing-packages.rst:303 msgid "" -"Pipenv manages dependencies on a per-project basis. To install packages, " -"change into your project's directory (or just an empty directory for this " -"tutorial) and run:" +"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 `. A full description of the " +"supported specifiers can be found in the :ref:`Version specifier " +"specification `. Below are some examples." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:73 -msgid "" -"Pipenv will install the `Requests`_ library and create a ``Pipfile`` for you " -"in your project's directory. The :ref:`Pipfile` is used to track which " -"dependencies your project needs in case you need to re-install them, such as " -"when you share your project with others. You should get output similar to " -"this (although the exact paths shown will vary):" +#: ../source/tutorials/installing-packages.rst:311 +msgid "To install the latest version of \"SomeProject\":" msgstr "" -#: ../source/tutorials/managing-dependencies.rst:109 -msgid "Using installed packages" -msgstr "Utilización de paquetes instalados" - -#: ../source/tutorials/managing-dependencies.rst:111 -msgid "" -"Now that Requests is installed you can create a simple :file:`main.py` file " -"to use it:" -msgstr "" +#: ../source/tutorials/installing-packages.rst:325 +msgid "To install a specific version:" +msgstr "Para instalar una versión específica:" -#: ../source/tutorials/managing-dependencies.rst:122 -msgid "Then you can run this script using ``pipenv run``:" +#: ../source/tutorials/installing-packages.rst:339 +msgid "To install greater than or equal to one version and less than another:" msgstr "" -#: ../source/tutorials/managing-dependencies.rst:128 -msgid "You should get output similar to this:" +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" msgstr "" -#: ../source/tutorials/managing-dependencies.rst:134 +#: ../source/tutorials/installing-packages.rst:369 msgid "" -"Using ``pipenv run`` ensures that your installed packages are available to " -"your script. It's also possible to spawn a new shell that ensures all " -"commands have access to your installed packages with ``pipenv shell``." +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:140 -#: ../source/tutorials/packaging-projects.rst:504 -msgid "Next steps" -msgstr "Próximos pasos" +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" -#: ../source/tutorials/managing-dependencies.rst:142 +#: ../source/tutorials/installing-packages.rst:376 msgid "" -"Congratulations, you now know how to effectively manage dependencies and " -"development environments on a collaborative Python project! ✨ 🍰 ✨" +":ref:`pip` can install from either :term:`Source Distributions (sdist) " +"` or :term:`Wheels `, but if both " +"are present on PyPI, pip will prefer a compatible :term:`wheel `. You " +"can override pip`s default behavior by e.g. using its :ref:`--no-binary ` option." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:145 +#: ../source/tutorials/installing-packages.rst:382 msgid "" -"If you're interested in creating and distributing your own Python packages, " -"see the :ref:`tutorial on packaging and distributing packages `." +":term:`Wheels ` are a pre-built :term:`distribution ` format that provides faster installation compared to :term:`Source " +"Distributions (sdist) `, especially when " +"a project contains compiled extensions." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:148 +#: ../source/tutorials/installing-packages.rst:387 msgid "" -"Note that when your application includes definitions of Python source " -"packages, they (and their dependencies) can be added to your ``pipenv`` " -"environment with ``pipenv install -e `` " -"(e.g. ``pipenv install -e .`` or ``pipenv install -e src``)." +"If :ref:`pip` does not find a wheel to install, it will locally build a " +"wheel and cache it for future installs, instead of rebuilding the source " +"distribution in the future." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:157 -msgid "Other Tools for Application Dependency Management" -msgstr "Otras herramientas para la gestión de las dependencias de aplicación" - -#: ../source/tutorials/managing-dependencies.rst:159 -msgid "" -"If you find this particular approach to managing application dependencies " -"isn't working well for you or your use case, you may want to explore these " -"other tools and techniques, listed in alphabetical order, to see if one of " -"them is a better fit:" +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:163 -msgid "" -"`hatch `_ for opinionated coverage of even " -"more steps in the project management workflow, such as incrementing versions " -"and creating new skeleton projects from project templates." +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" msgstr "" -#: ../source/tutorials/managing-dependencies.rst:166 +#: ../source/tutorials/installing-packages.rst:414 msgid "" -"`micropipenv `_ for a " -"lightweight wrapper around pip that supports ``requirements.txt``, Pipenv " -"and Poetry lock files, or converting them to pip-tools compatible output. " -"Designed for containerized Python applications, but not limited to them." +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" msgstr "" -#: ../source/tutorials/managing-dependencies.rst:170 +#: ../source/tutorials/installing-packages.rst:429 msgid "" -"`PDM `_ for a modern Python package " -"management relying on standards such as :pep:`517` and :pep:`621`." +"For more information see the `User Installs `_ section from the pip docs." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:172 +#: ../source/tutorials/installing-packages.rst:433 msgid "" -"`pip-tools `_ for creating a lock " -"file of all dependencies from a list of packages directly used in a project, " -"and ensuring that only those dependencies are installed." +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." msgstr "" -#: ../source/tutorials/managing-dependencies.rst:175 +#: ../source/tutorials/installing-packages.rst:436 msgid "" -"`Poetry `__ for a tool comparable " -"in scope to Pipenv that focuses more directly on use cases where the project " -"being managed is structured as a distributable Python package with a valid " -"``pyproject.toml`` file. By contrast, Pipenv explicitly avoids making the " -"assumption that the application being worked on will support distribution as " -"a ``pip``-installable Python package." +"If ``SomeProject`` defines any command-line scripts or console entry points, " +"``--user`` will cause them to be installed inside the `user base`_'s binary " +"directory, which may or may not already be present in your shell's :envvar:" +"`PATH`. (Starting in version 10, pip displays a warning when installing any " +"scripts to a directory outside :envvar:`PATH`.) If the scripts are not " +"available in your shell after installation, you'll need to add the directory " +"to your :envvar:`PATH`:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:2 -msgid "Packaging Python Projects" -msgstr "Empaquetamiento de proyectos Python" - -#: ../source/tutorials/packaging-projects.rst:4 +#: ../source/tutorials/installing-packages.rst:444 msgid "" -"This tutorial walks you through how to package a simple Python project. It " -"will show you how to add the necessary files and structure to create the " -"package, how to build the package, and how to upload it to the Python " -"Package Index (PyPI)." +"On Linux and macOS you can find the user base binary directory by running " +"``python -m site --user-base`` and adding ``bin`` to the end. For example, " +"this will typically print ``~/.local`` (with ``~`` expanded to the absolute " +"path to your home directory) so you'll need to add ``~/.local/bin`` to your " +"``PATH``. You can set your ``PATH`` permanently by `modifying ~/.profile`_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:10 +#: ../source/tutorials/installing-packages.rst:450 msgid "" -"If you have trouble running the commands in this tutorial, please copy the " -"command and its output, then `open an issue`_ on the `packaging-problems`_ " -"repository on GitHub. We'll do our best to help you!" +"On Windows you can find the user base binary directory by running ``py -m " +"site --user-site`` and replacing ``site-packages`` with ``Scripts``. For " +"example, this could return ``C:" +"\\Users\\Username\\AppData\\Roaming\\Python36\\site-packages`` so you would " +"need to set your ``PATH`` to include ``C:" +"\\Users\\Username\\AppData\\Roaming\\Python36\\Scripts``. You can set your " +"user ``PATH`` permanently in the `Control Panel`_. You may need to log out " +"for the ``PATH`` changes to take effect." msgstr "" -#: ../source/tutorials/packaging-projects.rst:18 +#: ../source/tutorials/installing-packages.rst:466 msgid "" -"Some of the commands require a newer version of :ref:`pip`, so start by " -"making sure you have the latest version installed:" +"Install a list of requirements specified in a :ref:`Requirements File `." msgstr "" -#: ../source/tutorials/packaging-projects.rst:35 -msgid "A simple project" -msgstr "Un proyecto sencillo" +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "Instalación a partir de un sistema de control de versiones" -#: ../source/tutorials/packaging-projects.rst:37 +#: ../source/tutorials/installing-packages.rst:484 msgid "" -"This tutorial uses a simple project named " -"``example_package_YOUR_USERNAME_HERE``. If your username is ``me``, then the " -"package would be ``example_package_me``; this ensures that you have a unique " -"package name that doesn't conflict with packages uploaded by other people " -"following this tutorial. We recommend following this tutorial as-is using " -"this project, before packaging your own project." +"Install a project from VCS in \"editable\" mode. For a full breakdown of " +"the syntax, see pip's section on :ref:`VCS Support `." msgstr "" -#: ../source/tutorials/packaging-projects.rst:44 -msgid "Create the following file structure locally:" -msgstr "Cree la estructura siguiente de manera local:" +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "Instalación a partir de otros índices" -#: ../source/tutorials/packaging-projects.rst:54 +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "Instalación a partir de un índice alternativo" + +#: ../source/tutorials/installing-packages.rst:522 msgid "" -"The directory containing the Python files should match the project name. " -"This simplifies the configuration and is more obvious to users who install " -"the package." +"Search an additional index during install, in addition to :term:`PyPI " +"`" msgstr "" -#: ../source/tutorials/packaging-projects.rst:57 -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 " -"[#namespace-packages]_." +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" msgstr "" -#: ../source/tutorials/packaging-projects.rst:60 +#: ../source/tutorials/installing-packages.rst:541 msgid "" -":file:`example.py` is an example of a module within the package that could " -"contain the logic (functions, classes, constants, etc.) of your package. " -"Open that file and enter the following content:" +"Installing from local src in :doc:`Development Mode `, i.e. in such a way that the project appears to be " +"installed, but yet is still editable from the src tree." msgstr "" -#: ../source/tutorials/packaging-projects.rst:69 -msgid "" -"If you are unfamiliar with Python's :term:`modules ` and :term:" -"`import packages `, take a few minutes to read over the " -"`Python documentation for packages and modules`_." +#: ../source/tutorials/installing-packages.rst:558 +msgid "You can also install normally from src" msgstr "" -#: ../source/tutorials/packaging-projects.rst:73 -msgid "" -"Once you create this structure, you'll want to run all of the commands in " -"this tutorial within the ``packaging_tutorial`` directory." +#: ../source/tutorials/installing-packages.rst:573 +msgid "Installing from local archives" msgstr "" -#: ../source/tutorials/packaging-projects.rst:81 -msgid "Creating the package files" -msgstr "Creación de los archivos del paquete" +#: ../source/tutorials/installing-packages.rst:575 +msgid "Install a particular source archive file." +msgstr "" -#: ../source/tutorials/packaging-projects.rst:83 +#: ../source/tutorials/installing-packages.rst:589 msgid "" -"You will now add files that are used to prepare the project for " -"distribution. When you're done, the project structure will look like this:" +"Install from a local directory containing archives (and don't check :term:" +"`PyPI `)" msgstr "" -#: ../source/tutorials/packaging-projects.rst:101 -msgid "Creating a test directory" -msgstr "Creación de un directorio de pruebas" +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "Instalación a partir de otras fuentes" -#: ../source/tutorials/packaging-projects.rst:103 -msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +#: ../source/tutorials/installing-packages.rst:611 +msgid "" +"To install from other data sources (for example Amazon S3 storage) you can " +"create a helper application that presents the data in a format compliant " +"with the :ref:`simple repository API `:, and use the " +"``--extra-index-url`` flag to direct pip to use that index." msgstr "" -#: ../source/tutorials/packaging-projects.rst:109 -msgid "Choosing a build backend" +#: ../source/tutorials/installing-packages.rst:623 +msgid "Installing Prereleases" msgstr "" -#: ../source/tutorials/packaging-projects.rst:111 +#: ../source/tutorials/installing-packages.rst:625 msgid "" -"Tools like :ref:`pip` and :ref:`build` do not actually convert your sources " -"into a :term:`distribution package ` (like a wheel); " -"that job is performed by a :term:`build backend `. The build " -"backend determines how your project will specify its configuration, " -"including metadata (information about the project, for example, the name and " -"tags that are displayed on PyPI) and input files. Build backends have " -"different levels of functionality, such as whether they support building :" -"term:`extension modules `, and you should choose one that " -"suits your needs and preferences." +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." msgstr "" -#: ../source/tutorials/packaging-projects.rst:120 -msgid "" -"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 `." -msgstr "" +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "Instalando \"Extras\"" -#: ../source/tutorials/packaging-projects.rst:127 +#: ../source/tutorials/installing-packages.rst:643 msgid "" -"Some build backends are part of larger tools that provide a command-line " -"interface with additional features like project initialization and version " -"management, as well as building, uploading, and installing packages. This " -"tutorial uses single-purpose tools that work independently." +"Extras are optional \"variants\" of a package, which may include additional " +"dependencies, and thereby enable additional functionality from the package. " +"If you wish to install an extra for a package which you know publishes one, " +"you can include it in the pip installation command:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:132 +#: ../source/tutorials/installing-packages.rst:666 msgid "" -"The :file:`pyproject.toml` tells :term:`build frontend ` " -"tools like :ref:`pip` and :ref:`build` which backend to use for your " -"project. Below are some examples for common build backends, but check your " -"backend's own documentation for more details." +"\"Secure\" in this context means using a modern browser or a tool like :" +"command:`curl` that verifies SSL certificates when downloading from https " +"URLs." msgstr "" -#: ../source/tutorials/packaging-projects.rst:170 +#: ../source/tutorials/installing-packages.rst:675 msgid "" -"The ``requires`` key is a list of packages that are needed to build your " -"package. The :term:`frontend ` should install them " -"automatically when building your package. Frontends usually run builds in " -"isolated environments, so omitting dependencies here may cause build-time " -"errors. This should always include your backend's package, and might have " -"other build-time dependencies." +"Beginning with Python 3.4, ``venv`` (a stdlib alternative to :ref:" +"`virtualenv`) will create virtualenv environments with ``pip`` pre-" +"installed, thereby making it an equal alternative to :ref:`virtualenv`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:177 +#: ../source/tutorials/installing-packages.rst:680 msgid "" -"The ``build-backend`` key is the name of the Python object that frontends " -"will use to perform the build." +"The compatible release specifier was accepted in :pep:`440` and support was " +"released in :ref:`setuptools` v8.0 and :ref:`pip` v6.0" msgstr "" -#: ../source/tutorials/packaging-projects.rst:180 +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "Gestión de las dependencias de aplicación" + +#: ../source/tutorials/managing-dependencies.rst:6 msgid "" -"Both of these values will be provided by the documentation for your build " -"backend, or generated by its command line interface. There should be no need " -"for you to customize these settings." +"The :ref:`package installation tutorial ` covered the " +"basics of getting set up to install and update Python packages." msgstr "" -#: ../source/tutorials/packaging-projects.rst:184 +#: ../source/tutorials/managing-dependencies.rst:9 msgid "" -"Additional configuration of the build tool will either be in a ``tool`` " -"section of the ``pyproject.toml``, or in a special file defined by the build " -"tool. For example, when using ``setuptools`` as your build backend, " -"additional configuration may be added to a ``setup.py`` or ``setup.cfg`` " -"file, and specifying ``setuptools.build_meta`` in your build allows the " -"tools to locate and use these automatically." +"However, running these commands interactively can get tedious even for your " +"own personal projects, and things get even more difficult when trying to set " +"up development environments automatically for projects with multiple " +"contributors." msgstr "" -#: ../source/tutorials/packaging-projects.rst:194 -msgid "Configuring metadata" -msgstr "Configuración de los metadatos" - -#: ../source/tutorials/packaging-projects.rst:196 +#: ../source/tutorials/managing-dependencies.rst:13 msgid "" -"Open :file:`pyproject.toml` and enter the following content. Change the " -"``name`` to include your username; this ensures that you have a unique " -"package name that doesn't conflict with packages uploaded by other people " -"following this tutorial." +"This tutorial walks you through the use of :ref:`Pipenv` to manage " +"dependencies for an application. It will show you how to install and use the " +"necessary tools and make strong recommendations on best practices." msgstr "" -#: ../source/tutorials/packaging-projects.rst:222 +#: ../source/tutorials/managing-dependencies.rst:17 msgid "" -"``name`` is the *distribution name* of your package. This can be any name as " -"long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also " -"must not already be taken on PyPI. **Be sure to update this with your " -"username** for this tutorial, as this ensures you won't try to upload a " -"package with the same name as one which already exists." +"Keep in mind that Python is used for a great many different purposes, and " +"precisely how you want to manage your dependencies may change based on how " +"you decide to publish your software. The guidance presented here is most " +"directly applicable to the development and deployment of network services " +"(including web applications), but is also very well suited to managing " +"development and testing environments for any kind of project." msgstr "" -#: ../source/tutorials/packaging-projects.rst:227 +#: ../source/tutorials/managing-dependencies.rst:24 msgid "" -"``version`` is the package version. (Some build backends allow it to be " -"specified another way, such as from a file or Git tag.)" +"For alternatives, see `Other Tools for Application Dependency Management`_." msgstr "" +"Para alternativas, mira `Other Tools for Application Dependency Management`_." -#: ../source/tutorials/packaging-projects.rst:229 +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "Instalación de Pipenv" + +#: ../source/tutorials/managing-dependencies.rst:29 msgid "" -"``authors`` is used to identify the author of the package; you specify a " -"name and an email for each author. You can also list ``maintainers`` in the " -"same format." +":ref:`Pipenv` is a dependency manager for Python projects. If you're " +"familiar with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit " +"to those tools. While :ref:`pip` alone is often sufficient for personal use, " +"Pipenv is recommended for collaborative projects as it's a higher-level tool " +"that simplifies dependency management for common use cases." msgstr "" -#: ../source/tutorials/packaging-projects.rst:232 -msgid "``description`` is a short, one-sentence summary of the package." +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:233 +#: ../source/tutorials/managing-dependencies.rst:51 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:`pyproject." -"toml guide `." +"This does a `user installation`_ to prevent breaking any system-wide " +"packages. If ``pipenv`` isn't available in your shell after installation, " +"you'll need to add the :py:data:`user base `'s binary " +"directory to your ``PATH``. See :ref:`Installing to the User Site` for more " +"information." msgstr "" -#: ../source/tutorials/packaging-projects.rst:238 +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "Instalación de paquetes para su proyecto" + +#: ../source/tutorials/managing-dependencies.rst:64 msgid "" -"``requires-python`` gives the versions of Python supported by your project. " -"An installer like :ref:`pip` will look back through older versions of " -"packages until it finds one that has a matching Python version." +"Pipenv manages dependencies on a per-project basis. To install packages, " +"change into your project's directory (or just an empty directory for this " +"tutorial) and run:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:241 +#: ../source/tutorials/managing-dependencies.rst:73 msgid "" -"``classifiers`` gives the index and :ref:`pip` some additional metadata " -"about your package. In this case, the package is only compatible with Python " -"3, is licensed under the MIT license, and is OS-independent. You should " -"always include at least which version(s) of Python your package works on, " -"which license your package is available under, and which operating systems " -"your package will work on. For a complete list of classifiers, see https://" -"pypi.org/classifiers/." +"Pipenv will install the `Requests`_ library and create a ``Pipfile`` for you " +"in your project's directory. The :ref:`Pipfile` is used to track which " +"dependencies your project needs in case you need to re-install them, such as " +"when you share your project with others. You should get output similar to " +"this (although the exact paths shown will vary):" msgstr "" -#: ../source/tutorials/packaging-projects.rst:248 +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "Utilización de paquetes instalados" + +#: ../source/tutorials/managing-dependencies.rst:111 msgid "" -"``urls`` lets you list any number of extra links to show on PyPI. Generally " -"this could be to the source, documentation, issue trackers, etc." +"Now that Requests is installed you can create a simple :file:`main.py` file " +"to use it:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:251 -msgid "" -"See the :ref:`pyproject.toml guide ` 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." +#: ../source/tutorials/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:258 -msgid "Creating README.md" +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:260 +#: ../source/tutorials/managing-dependencies.rst:134 msgid "" -"Open :file:`README.md` and enter the following content. You can customize " -"this if you'd like." +"Using ``pipenv run`` ensures that your installed packages are available to " +"your script. It's also possible to spawn a new shell that ensures all " +"commands have access to your installed packages with ``pipenv shell``." msgstr "" -#: ../source/tutorials/packaging-projects.rst:273 -msgid "Creating a LICENSE" +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:504 +msgid "Next steps" +msgstr "Próximos pasos" + +#: ../source/tutorials/managing-dependencies.rst:142 +msgid "" +"Congratulations, you now know how to effectively manage dependencies and " +"development environments on a collaborative Python project! ✨ 🍰 ✨" msgstr "" -#: ../source/tutorials/packaging-projects.rst:275 +#: ../source/tutorials/managing-dependencies.rst:145 msgid "" -"It's important for every package uploaded to the Python Package Index to " -"include a license. This tells users who install your package the terms under " -"which they can use your package. For help picking a license, see https://" -"choosealicense.com/. Once you have chosen a license, open :file:`LICENSE` " -"and enter the license text. For example, if you had chosen the MIT license:" +"If you're interested in creating and distributing your own Python packages, " +"see the :ref:`tutorial on packaging and distributing packages `." msgstr "" -#: ../source/tutorials/packaging-projects.rst:304 +#: ../source/tutorials/managing-dependencies.rst:148 msgid "" -"Most build backends automatically include license files in packages. See " -"your backend's documentation for more details." +"Note that when your application includes definitions of Python source " +"packages, they (and their dependencies) can be added to your ``pipenv`` " +"environment with ``pipenv install -e `` " +"(e.g. ``pipenv install -e .`` or ``pipenv install -e src``)." msgstr "" -#: ../source/tutorials/packaging-projects.rst:309 -msgid "Including other files" +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "Otras herramientas para la gestión de las dependencias de aplicación" + +#: ../source/tutorials/managing-dependencies.rst:159 +msgid "" +"If you find this particular approach to managing application dependencies " +"isn't working well for you or your use case, you may want to explore these " +"other tools and techniques, listed in alphabetical order, to see if one of " +"them is a better fit:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:311 +#: ../source/tutorials/managing-dependencies.rst:163 msgid "" -"The files listed above will be included automatically in your :term:`source " -"distribution `. If you want to include " -"additional files, see the documentation for your build backend." +"`hatch `_ for opinionated coverage of even " +"more steps in the project management workflow, such as incrementing versions " +"and creating new skeleton projects from project templates." msgstr "" -#: ../source/tutorials/packaging-projects.rst:318 -msgid "Generating distribution archives" +#: ../source/tutorials/managing-dependencies.rst:166 +msgid "" +"`micropipenv `_ for a " +"lightweight wrapper around pip that supports ``requirements.txt``, Pipenv " +"and Poetry lock files, or converting them to pip-tools compatible output. " +"Designed for containerized Python applications, but not limited to them." msgstr "" -#: ../source/tutorials/packaging-projects.rst:320 +#: ../source/tutorials/managing-dependencies.rst:170 msgid "" -"The next step is to generate :term:`distribution packages ` for the package. These are archives that are uploaded to the " -"Python Package Index and can be installed by :ref:`pip`." +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:324 -msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +#: ../source/tutorials/managing-dependencies.rst:172 +msgid "" +"`pip-tools `_ for creating a lock " +"file of all dependencies from a list of packages directly used in a project, " +"and ensuring that only those dependencies are installed." msgstr "" -#: ../source/tutorials/packaging-projects.rst:338 +#: ../source/tutorials/managing-dependencies.rst:175 msgid "" -"If you have trouble installing these, see the :doc:`installing-packages` " -"tutorial." +"`Poetry `__ for a tool comparable " +"in scope to Pipenv that focuses more directly on use cases where the project " +"being managed is structured as a distributable Python package with a valid " +"``pyproject.toml`` file. By contrast, Pipenv explicitly avoids making the " +"assumption that the application being worked on will support distribution as " +"a ``pip``-installable Python package." msgstr "" -#: ../source/tutorials/packaging-projects.rst:341 +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "Empaquetamiento de proyectos Python" + +#: ../source/tutorials/packaging-projects.rst:4 msgid "" -"Now run this command from the same directory where :file:`pyproject.toml` is " -"located:" +"This tutorial walks you through how to package a simple Python project. It " +"will show you how to add the necessary files and structure to create the " +"package, how to build the package, and how to upload it to the Python " +"Package Index (PyPI)." msgstr "" -#: ../source/tutorials/packaging-projects.rst:355 +#: ../source/tutorials/packaging-projects.rst:10 msgid "" -"This command should output a lot of text and once completed should generate " -"two files in the :file:`dist` directory:" +"If you have trouble running the commands in this tutorial, please copy the " +"command and its output, then `open an issue`_ on the `packaging-problems`_ " +"repository on GitHub. We'll do our best to help you!" msgstr "" -#: ../source/tutorials/packaging-projects.rst:365 +#: ../source/tutorials/packaging-projects.rst:18 msgid "" -"The ``tar.gz`` file is a :term:`source distribution ` whereas the ``.whl`` file is a :term:`built distribution `. Newer :ref:`pip` versions preferentially install built " -"distributions, but will fall back to source distributions if needed. You " -"should always upload a source distribution and provide built distributions " -"for the platforms your project is compatible with. In this case, our example " -"package is compatible with Python on any platform so only one built " -"distribution is needed." +"Some of the commands require a newer version of :ref:`pip`, so start by " +"making sure you have the latest version installed:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:374 -msgid "Uploading the distribution archives" +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "Un proyecto sencillo" + +#: ../source/tutorials/packaging-projects.rst:37 +msgid "" +"This tutorial uses a simple project named " +"``example_package_YOUR_USERNAME_HERE``. If your username is ``me``, then the " +"package would be ``example_package_me``; this ensures that you have a unique " +"package name that doesn't conflict with packages uploaded by other people " +"following this tutorial. We recommend following this tutorial as-is using " +"this project, before packaging your own project." msgstr "" -#: ../source/tutorials/packaging-projects.rst:376 -msgid "Finally, it's time to upload your package to the Python Package Index!" +#: ../source/tutorials/packaging-projects.rst:44 +msgid "Create the following file structure locally:" +msgstr "Cree la estructura siguiente de manera local:" + +#: ../source/tutorials/packaging-projects.rst:54 +msgid "" +"The directory containing the Python files should match the project name. " +"This simplifies the configuration and is more obvious to users who install " +"the package." msgstr "" -#: ../source/tutorials/packaging-projects.rst:378 +#: ../source/tutorials/packaging-projects.rst:57 msgid "" -"The first thing you'll need to do is register an account on TestPyPI, which " -"is a separate instance of the package index intended for testing and " -"experimentation. It's great for things like this tutorial where we don't " -"necessarily want to upload to the real index. To register an account, go to " -"https://test.pypi.org/account/register/ and complete the steps on that page. " -"You will also need to verify your email address before you're able to upload " -"any packages. For more details, see :doc:`/guides/using-testpypi`." +":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 " +"[#namespace-packages]_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:386 +#: ../source/tutorials/packaging-projects.rst:60 msgid "" -"To securely upload your project, you'll need a PyPI `API token`_. Create one " -"at https://test.pypi.org/manage/account/#api-tokens, setting the \"Scope\" " -"to \"Entire account\". **Don't close the page until you have copied and " -"saved the token — you won't see that token again.**" +":file:`example.py` is an example of a module within the package that could " +"contain the logic (functions, classes, constants, etc.) of your package. " +"Open that file and enter the following content:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:393 +#: ../source/tutorials/packaging-projects.rst:69 msgid "" -"Now that you are registered, you can use :ref:`twine` to upload the " -"distribution packages. You'll need to install Twine:" +"If you are unfamiliar with Python's :term:`modules ` and :term:" +"`import packages `, take a few minutes to read over the " +"`Python documentation for packages and modules`_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:408 +#: ../source/tutorials/packaging-projects.rst:73 msgid "" -"Once installed, run Twine to upload all of the archives under :file:`dist`:" +"Once you create this structure, you'll want to run all of the commands in " +"this tutorial within the ``packaging_tutorial`` directory." msgstr "" -#: ../source/tutorials/packaging-projects.rst:422 +#: ../source/tutorials/packaging-projects.rst:81 +msgid "Creating the package files" +msgstr "Creación de los archivos del paquete" + +#: ../source/tutorials/packaging-projects.rst:83 msgid "" -"You will be prompted for a username and password. For the username, use " -"``__token__``. For the password, use the token value, including the ``pypi-" -"`` prefix." +"You will now add files that are used to prepare the project for " +"distribution. When you're done, the project structure will look like this:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:426 -msgid "After the command completes, you should see output similar to this:" +#: ../source/tutorials/packaging-projects.rst:101 +msgid "Creating a test directory" +msgstr "Creación de un directorio de pruebas" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." msgstr "" -#: ../source/tutorials/packaging-projects.rst:437 -msgid "" -"Once uploaded, your package should be viewable on TestPyPI; for example: " -"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +#: ../source/tutorials/packaging-projects.rst:109 +msgid "Choosing a build backend" msgstr "" -#: ../source/tutorials/packaging-projects.rst:442 -msgid "Installing your newly uploaded package" -msgstr "Instalación de su paquete recién cargado" +#: ../source/tutorials/packaging-projects.rst:111 +msgid "" +"Tools like :ref:`pip` and :ref:`build` do not actually convert your sources " +"into a :term:`distribution package ` (like a wheel); " +"that job is performed by a :term:`build backend `. The build " +"backend determines how your project will specify its configuration, " +"including metadata (information about the project, for example, the name and " +"tags that are displayed on PyPI) and input files. Build backends have " +"different levels of functionality, such as whether they support building :" +"term:`extension modules `, and you should choose one that " +"suits your needs and preferences." +msgstr "" -#: ../source/tutorials/packaging-projects.rst:444 +#: ../source/tutorials/packaging-projects.rst:120 msgid "" -"You can use :ref:`pip` to install your package and verify that it works. " -"Create a :ref:`virtual environment ` and install your package from TestPyPI:" +"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 `." msgstr "" -#: ../source/tutorials/packaging-projects.rst:460 -msgid "Make sure to specify your username in the package name!" +#: ../source/tutorials/packaging-projects.rst:127 +msgid "" +"Some build backends are part of larger tools that provide a command-line " +"interface with additional features like project initialization and version " +"management, as well as building, uploading, and installing packages. This " +"tutorial uses single-purpose tools that work independently." msgstr "" -#: ../source/tutorials/packaging-projects.rst:462 +#: ../source/tutorials/packaging-projects.rst:132 msgid "" -"pip should install the package from TestPyPI and the output should look " -"something like this:" +"The :file:`pyproject.toml` tells :term:`build frontend ` " +"tools like :ref:`pip` and :ref:`build` which backend to use for your " +"project. Below are some examples for common build backends, but check your " +"backend's own documentation for more details." msgstr "" -#: ../source/tutorials/packaging-projects.rst:472 +#: ../source/tutorials/packaging-projects.rst:170 msgid "" -"This example uses ``--index-url`` flag to specify TestPyPI instead of live " -"PyPI. Additionally, it specifies ``--no-deps``. Since TestPyPI doesn't have " -"the same packages as the live PyPI, it's possible that attempting to install " -"dependencies may fail or install something unexpected. While our example " -"package doesn't have any dependencies, it's a good practice to avoid " -"installing dependencies when using TestPyPI." +"The ``requires`` key is a list of packages that are needed to build your " +"package. The :term:`frontend ` should install them " +"automatically when building your package. Frontends usually run builds in " +"isolated environments, so omitting dependencies here may cause build-time " +"errors. This should always include your backend's package, and might have " +"other build-time dependencies." msgstr "" -#: ../source/tutorials/packaging-projects.rst:479 +#: ../source/tutorials/packaging-projects.rst:177 msgid "" -"You can test that it was installed correctly by importing the package. Make " -"sure you're still in your virtual environment, then run Python:" +"The ``build-backend`` key is the name of the Python object that frontends " +"will use to perform the build." msgstr "" -#: ../source/tutorials/packaging-projects.rst:494 -msgid "and import the package:" +#: ../source/tutorials/packaging-projects.rst:180 +msgid "" +"Both of these values will be provided by the documentation for your build " +"backend, or generated by its command line interface. There should be no need " +"for you to customize these settings." msgstr "" -#: ../source/tutorials/packaging-projects.rst:506 +#: ../source/tutorials/packaging-projects.rst:184 msgid "" -"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " -"✨" +"Additional configuration of the build tool will either be in a ``tool`` " +"section of the ``pyproject.toml``, or in a special file defined by the build " +"tool. For example, when using ``setuptools`` as your build backend, " +"additional configuration may be added to a ``setup.py`` or ``setup.cfg`` " +"file, and specifying ``setuptools.build_meta`` in your build allows the " +"tools to locate and use these automatically." msgstr "" -#: ../source/tutorials/packaging-projects.rst:509 +#: ../source/tutorials/packaging-projects.rst:194 +msgid "Configuring metadata" +msgstr "Configuración de los metadatos" + +#: ../source/tutorials/packaging-projects.rst:196 msgid "" -"Keep in mind that this tutorial showed you how to upload your package to " -"Test PyPI, which isn't a permanent storage. The Test system occasionally " -"deletes packages and accounts. It is best to use TestPyPI for testing and " -"experiments like this tutorial." +"Open :file:`pyproject.toml` and enter the following content. Change the " +"``name`` to include your username; this ensures that you have a unique " +"package name that doesn't conflict with packages uploaded by other people " +"following this tutorial." msgstr "" -#: ../source/tutorials/packaging-projects.rst:514 +#: ../source/tutorials/packaging-projects.rst:222 msgid "" -"When you are ready to upload a real package to the Python Package Index you " -"can do much the same as you did in this tutorial, but with these important " -"differences:" +"``name`` is the *distribution name* of your package. This can be any name as " +"long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also " +"must not already be taken on PyPI. **Be sure to update this with your " +"username** for this tutorial, as this ensures you won't try to upload a " +"package with the same name as one which already exists." msgstr "" -#: ../source/tutorials/packaging-projects.rst:518 +#: ../source/tutorials/packaging-projects.rst:227 msgid "" -"Choose a memorable and unique name for your package. You don't have to " -"append your username as you did in the tutorial, but you can't use an " -"existing name." +"``version`` is the package version. (Some build backends allow it to be " +"specified another way, such as from a file or Git tag.)" msgstr "" -#: ../source/tutorials/packaging-projects.rst:520 +#: ../source/tutorials/packaging-projects.rst:229 msgid "" -"Register an account on https://pypi.org - note that these are two separate " -"servers and the login details from the test server are not shared with the " -"main server." +"``authors`` is used to identify the author of the package; you specify a " +"name and an email for each author. You can also list ``maintainers`` in the " +"same format." msgstr "" -#: ../source/tutorials/packaging-projects.rst:523 -msgid "" -"Use ``twine upload dist/*`` to upload your package and enter your " -"credentials for the account you registered on the real PyPI. Now that " -"you're uploading the package in production, you don't need to specify ``--" -"repository``; the package will upload to https://pypi.org/ by default." +#: ../source/tutorials/packaging-projects.rst:232 +msgid "``description`` is a short, one-sentence summary of the package." msgstr "" -#: ../source/tutorials/packaging-projects.rst:527 +#: ../source/tutorials/packaging-projects.rst:233 msgid "" -"Install your package from the real PyPI using ``python3 -m pip install [your-" -"package]``." +"``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:`pyproject." +"toml guide `." msgstr "" -#: ../source/tutorials/packaging-projects.rst:529 +#: ../source/tutorials/packaging-projects.rst:238 msgid "" -"At this point if you want to read more on packaging Python libraries here " -"are some things you can do:" +"``requires-python`` gives the versions of Python supported by your project. " +"An installer like :ref:`pip` will look back through older versions of " +"packages until it finds one that has a matching Python version." msgstr "" -#: ../source/tutorials/packaging-projects.rst:532 +#: ../source/tutorials/packaging-projects.rst:241 msgid "" -"Read about advanced configuration for your chosen build backend: `Hatchling " -"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +"``classifiers`` gives the index and :ref:`pip` some additional metadata " +"about your package. In this case, the package is only compatible with Python " +"3, is licensed under the MIT license, and is OS-independent. You should " +"always include at least which version(s) of Python your package works on, " +"which license your package is available under, and which operating systems " +"your package will work on. For a complete list of classifiers, see https://" +"pypi.org/classifiers/." msgstr "" -#: ../source/tutorials/packaging-projects.rst:536 +#: ../source/tutorials/packaging-projects.rst:248 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." +"``urls`` lets you list any number of extra links to show on PyPI. Generally " +"this could be to the source, documentation, issue trackers, etc." msgstr "" -#: ../source/tutorials/packaging-projects.rst:539 +#: ../source/tutorials/packaging-projects.rst:251 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`." +"See the :ref:`pyproject.toml guide ` 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." msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 -msgid "Notes" +#: ../source/tutorials/packaging-projects.rst:258 +msgid "Creating README.md" msgstr "" -#: ../source/tutorials/packaging-projects.rst:549 +#: ../source/tutorials/packaging-projects.rst:260 msgid "" -"Technically, you can also create Python packages without an ``__init__.py`` " -"file, but those are called :doc:`namespace packages ` and considered an **advanced topic** (not covered in " -"this tutorial). If you are only getting started with Python packaging, it is " -"recommended to stick with *regular packages* and ``__init__.py`` (even if " -"the file is empty)." +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." msgstr "" -#: ../source/discussions/package-formats.rst:5 -#, fuzzy -msgid "Package Formats" -msgstr "Índice de paquetes" +#: ../source/tutorials/packaging-projects.rst:273 +msgid "Creating a LICENSE" +msgstr "" -#: ../source/discussions/package-formats.rst:7 +#: ../source/tutorials/packaging-projects.rst:275 msgid "" -"This page discusses the file formats that are used to distribute Python " -"packages and the differences between them." +"It's important for every package uploaded to the Python Package Index to " +"include a license. This tells users who install your package the terms under " +"which they can use your package. For help picking a license, see https://" +"choosealicense.com/. Once you have chosen a license, open :file:`LICENSE` " +"and enter the license text. For example, if you had chosen the MIT license:" msgstr "" -#: ../source/discussions/package-formats.rst:10 +#: ../source/tutorials/packaging-projects.rst:304 msgid "" -"You will find files in two formats on package indices such as PyPI_: " -"**source distributions**, or **sdists** for short, and **binary " -"distributions**, commonly called **wheels**. For example, the `PyPI page " -"for pip 23.3.1 `_ lets you download two files, ``pip-23.3.1.tar." -"gz`` and ``pip-23.3.1-py3-none-any.whl``. The former is an sdist, the " -"latter is a wheel. As explained below, these serve different purposes. When " -"publishing a package on PyPI (or elsewhere), you should always upload both " -"an sdist and one or more wheel." +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details." msgstr "" -#: ../source/discussions/package-formats.rst:21 -#, fuzzy -msgid "What is a source distribution?" -msgstr "Paquete de Distribución" +#: ../source/tutorials/packaging-projects.rst:309 +msgid "Including other files" +msgstr "" -#: ../source/discussions/package-formats.rst:23 +#: ../source/tutorials/packaging-projects.rst:311 msgid "" -"Conceptually, a source distribution is an archive of the source code in raw " -"form. Concretely, an sdist is a ``.tar.gz`` archive containing the source " -"code plus an additional special file called ``PKG-INFO``, which holds the " -"project metadata. The presence of this file helps packaging tools to be more " -"efficient by not needing to compute the metadata themselves. The ``PKG-" -"INFO`` file follows the format specified in :ref:`core-metadata` and is not " -"intended to be written by hand [#core-metadata-format]_." +"The files listed above will be included automatically in your :term:`source " +"distribution `. If you want to include " +"additional files, see the documentation for your build backend." msgstr "" -#: ../source/discussions/package-formats.rst:31 -msgid "" -"You can thus inspect the contents of an sdist by unpacking it using standard " -"tools to work with tar archives, such as ``tar -xvf`` on UNIX platforms " -"(like Linux and macOS), or :ref:`the command line interface of Python's " -"tarfile module ` on any platform." +#: ../source/tutorials/packaging-projects.rst:318 +msgid "Generating distribution archives" msgstr "" -#: ../source/discussions/package-formats.rst:36 +#: ../source/tutorials/packaging-projects.rst:320 msgid "" -"Sdists serve several purposes in the packaging ecosystem. When :ref:`pip`, " -"the standard Python package installer, cannot find a wheel to install, it " -"will fall back on downloading a source distribution, compiling a wheel from " -"it, and installing the wheel. Furthermore, sdists are often used as the " -"package source by downstream packagers (such as Linux distributions, Conda, " -"Homebrew and MacPorts on macOS, ...), who, for various reasons, may prefer " -"them over, e.g., pulling from a Git repository." +"The next step is to generate :term:`distribution packages ` for the package. These are archives that are uploaded to the " +"Python Package Index and can be installed by :ref:`pip`." msgstr "" -#: ../source/discussions/package-formats.rst:44 -msgid "" -"A source distribution is recognized by its file name, which has the form :" -"samp:`{package_name}-{version}.tar.gz`, e.g., ``pip-23.3.1.tar.gz``." +#: ../source/tutorials/packaging-projects.rst:324 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" msgstr "" -#: ../source/discussions/package-formats.rst:50 +#: ../source/tutorials/packaging-projects.rst:338 msgid "" -"If you want technical details on the sdist format, read the :ref:`sdist " -"specification `." +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." msgstr "" -#: ../source/discussions/package-formats.rst:55 -msgid "What is a wheel?" +#: ../source/tutorials/packaging-projects.rst:341 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" msgstr "" -#: ../source/discussions/package-formats.rst:57 +#: ../source/tutorials/packaging-projects.rst:355 msgid "" -"Conceptually, a wheel contains exactly the files that need to be copied when " -"installing the package." +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" msgstr "" -#: ../source/discussions/package-formats.rst:60 +#: ../source/tutorials/packaging-projects.rst:365 msgid "" -"There is a big difference between sdists and wheels for packages with :term:" -"`extension modules `, written in compiled languages like " -"C, C++ and Rust, which need to be compiled into platform-dependent machine " -"code. With these packages, wheels do not contain source code (like C source " -"files) but compiled, executable code (like ``.so`` files on Linux or DLLs on " -"Windows)." +"The ``tar.gz`` file is a :term:`source distribution ` whereas the ``.whl`` file is a :term:`built distribution `. Newer :ref:`pip` versions preferentially install built " +"distributions, but will fall back to source distributions if needed. You " +"should always upload a source distribution and provide built distributions " +"for the platforms your project is compatible with. In this case, our example " +"package is compatible with Python on any platform so only one built " +"distribution is needed." msgstr "" -#: ../source/discussions/package-formats.rst:66 -msgid "" -"Furthermore, while there is only one sdist per version of a project, there " -"may be many wheels. Again, this is most relevant in the context of extension " -"modules. The compiled code of an extension module is tied to an operating " -"system and processor architecture, and often also to the version of the " -"Python interpreter (unless the :ref:`Python stable ABI ` " -"is used)." +#: ../source/tutorials/packaging-projects.rst:374 +msgid "Uploading the distribution archives" msgstr "" -#: ../source/discussions/package-formats.rst:72 -msgid "" -"For pure-Python packages, the difference between sdists and wheels is less " -"marked. There is normally one single wheel, for all platforms and Python " -"versions. Python is an interpreted language, which does not need ahead-of-" -"time compilation, so wheels contain ``.py`` files just like sdists." +#: ../source/tutorials/packaging-projects.rst:376 +msgid "Finally, it's time to upload your package to the Python Package Index!" msgstr "" -#: ../source/discussions/package-formats.rst:77 +#: ../source/tutorials/packaging-projects.rst:378 msgid "" -"If you are wondering about ``.pyc`` bytecode files: they are not included in " -"wheels, since they are cheap to generate, and including them would " -"unnecessarily force a huge number of packages to distribute one wheel per " -"Python version instead of one single wheel. Instead, installers like :ref:" -"`pip` generate them while installing the package." +"The first thing you'll need to do is register an account on TestPyPI, which " +"is a separate instance of the package index intended for testing and " +"experimentation. It's great for things like this tutorial where we don't " +"necessarily want to upload to the real index. To register an account, go to " +"https://test.pypi.org/account/register/ and complete the steps on that page. " +"You will also need to verify your email address before you're able to upload " +"any packages. For more details, see :doc:`/guides/using-testpypi`." msgstr "" -#: ../source/discussions/package-formats.rst:83 +#: ../source/tutorials/packaging-projects.rst:386 msgid "" -"With that being said, there are still important differences between sdists " -"and wheels, even for pure Python projects. Wheels are meant to contain " -"exactly what is to be installed, and nothing more. In particular, wheels " -"should never include tests and documentation, while sdists commonly do. " -"Also, the wheel format is more complex than sdist. For example, it includes " -"a special file -- called ``RECORD`` -- that lists all files in the wheel " -"along with a hash of their content, as a safety check of the download's " -"integrity." +"To securely upload your project, you'll need a PyPI `API token`_. Create one " +"at https://test.pypi.org/manage/account/#api-tokens, setting the \"Scope\" " +"to \"Entire account\". **Don't close the page until you have copied and " +"saved the token — you won't see that token again.**" msgstr "" -#: ../source/discussions/package-formats.rst:91 +#: ../source/tutorials/packaging-projects.rst:393 msgid "" -"At a glance, you might wonder if wheels are really needed for \"plain and " -"basic\" pure Python projects. Keep in mind that due to the flexibility of " -"sdists, installers like pip cannot install from sdists directly -- they need " -"to first build a wheel, by invoking the :term:`build backend` that the sdist " -"specifies (the build backend may do all sorts of transformations while " -"building the wheel, such as compiling C extensions). For this reason, even " -"for a pure Python project, you should always upload *both* an sdist and a " -"wheel to PyPI or other package indices. This makes installation much faster " -"for your users, since a wheel is directly installable. By only including " -"files that must be installed, wheels also make for smaller downloads." +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" msgstr "" -#: ../source/discussions/package-formats.rst:102 +#: ../source/tutorials/packaging-projects.rst:408 msgid "" -"On the technical level, a wheel is a ZIP archive (unlike sdists which are " -"TAR archives). You can inspect its contents by unpacking it as a normal ZIP " -"archive, e.g., using ``unzip`` on UNIX platforms like Linux and macOS, " -"``Expand-Archive`` in Powershell on Windows, or :ref:`the command line " -"interface of Python's zipfile module `. This can " -"be very useful to check that the wheel includes all the files you need it to." +"Once installed, run Twine to upload all of the archives under :file:`dist`:" msgstr "" -#: ../source/discussions/package-formats.rst:109 +#: ../source/tutorials/packaging-projects.rst:422 msgid "" -"Inside a wheel, you will find the package's files, plus an additional " -"directory called :samp:`{package_name}-{version}.dist-info`. This directory " -"contains various files, including a ``METADATA`` file which is the " -"equivalent of ``PKG-INFO`` in sdists, as well as ``RECORD``. This can be " -"useful to ensure no files are missing from your wheels." +"You will be prompted for a username and password. For the username, use " +"``__token__``. For the password, use the token value, including the ``pypi-" +"`` prefix." msgstr "" -#: ../source/discussions/package-formats.rst:115 -msgid "" -"The file name of a wheel (ignoring some rarely used features) looks like " -"this: :samp:`{package_name}-{version}-{python_tag}-{abi_tag}-{platform_tag}." -"whl`. This naming convention identifies which platforms and Python versions " -"the wheel is compatible with. For example, the name ``pip-23.3.1-py3-none-" -"any.whl`` means that:" +#: ../source/tutorials/packaging-projects.rst:426 +msgid "After the command completes, you should see output similar to this:" msgstr "" -#: ../source/discussions/package-formats.rst:121 +#: ../source/tutorials/packaging-projects.rst:437 msgid "" -"(``py3``) This wheel can be installed on any implementation of Python 3, " -"whether CPython, the most widely used Python implementation, or an " -"alternative implementation like PyPy_;" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." msgstr "" -#: ../source/discussions/package-formats.rst:124 -msgid "(``none``) It does not depend on the Python version;" +#: ../source/tutorials/packaging-projects.rst:442 +msgid "Installing your newly uploaded package" +msgstr "Instalación de su paquete recién cargado" + +#: ../source/tutorials/packaging-projects.rst:444 +msgid "" +"You can use :ref:`pip` to install your package and verify that it works. " +"Create a :ref:`virtual environment ` and install your package from TestPyPI:" msgstr "" -#: ../source/discussions/package-formats.rst:125 -msgid "(``any``) It does not depend on the platform." +#: ../source/tutorials/packaging-projects.rst:460 +msgid "Make sure to specify your username in the package name!" msgstr "" -#: ../source/discussions/package-formats.rst:127 +#: ../source/tutorials/packaging-projects.rst:462 msgid "" -"The pattern ``py3-none-any`` is common for pure Python projects. Packages " -"with extension modules typically ship multiple wheels with more complex tags." +"pip should install the package from TestPyPI and the output should look " +"something like this:" msgstr "" -#: ../source/discussions/package-formats.rst:130 +#: ../source/tutorials/packaging-projects.rst:472 msgid "" -"All technical details on the wheel format can be found in the :ref:`wheel " -"specification `." +"This example uses ``--index-url`` flag to specify TestPyPI instead of live " +"PyPI. Additionally, it specifies ``--no-deps``. Since TestPyPI doesn't have " +"the same packages as the live PyPI, it's possible that attempting to install " +"dependencies may fail or install something unexpected. While our example " +"package doesn't have any dependencies, it's a good practice to avoid " +"installing dependencies when using TestPyPI." msgstr "" -#: ../source/discussions/package-formats.rst:138 -#, fuzzy -msgid "What about eggs?" -msgstr "¿Qué pasa con los pasos de construcción personalizados?" - -#: ../source/discussions/package-formats.rst:140 +#: ../source/tutorials/packaging-projects.rst:479 msgid "" -"\"Egg\" is an old package format that has been replaced with the wheel " -"format. It should not be used anymore. Since August 2023, PyPI `rejects egg " -"uploads `_." +"You can test that it was installed correctly by importing the package. Make " +"sure you're still in your virtual environment, then run Python:" msgstr "" -#: ../source/discussions/package-formats.rst:144 -msgid "Here's a breakdown of the important differences between wheel and egg." +#: ../source/tutorials/packaging-projects.rst:494 +msgid "and import the package:" msgstr "" -#: ../source/discussions/package-formats.rst:146 +#: ../source/tutorials/packaging-projects.rst:506 msgid "" -"The egg format was introduced by :ref:`setuptools` in 2004, whereas the " -"wheel format was introduced by :pep:`427` in 2012." +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" msgstr "" -#: ../source/discussions/package-formats.rst:149 +#: ../source/tutorials/packaging-projects.rst:509 msgid "" -"Wheel has an :doc:`official standard specification `. Egg did not." +"Keep in mind that this tutorial showed you how to upload your package to " +"Test PyPI, which isn't a permanent storage. The Test system occasionally " +"deletes packages and accounts. It is best to use TestPyPI for testing and " +"experiments like this tutorial." msgstr "" -#: ../source/discussions/package-formats.rst:152 +#: ../source/tutorials/packaging-projects.rst:514 msgid "" -"Wheel is a :term:`distribution ` format, i.e a " -"packaging format. [#wheel-importable]_ Egg was both a distribution format " -"and a runtime installation format (if left zipped), and was designed to be " -"importable." +"When you are ready to upload a real package to the Python Package Index you " +"can do much the same as you did in this tutorial, but with these important " +"differences:" msgstr "" -#: ../source/discussions/package-formats.rst:156 +#: ../source/tutorials/packaging-projects.rst:518 msgid "" -"Wheel archives do not include ``.pyc`` files. Therefore, when the " -"distribution only contains Python files (i.e. no compiled extensions), and " -"is compatible with Python 2 and 3, it's possible for a wheel to be " -"\"universal\", similar to an :term:`sdist `." +"Choose a memorable and unique name for your package. You don't have to " +"append your username as you did in the tutorial, but you can't use an " +"existing name." msgstr "" -#: ../source/discussions/package-formats.rst:161 +#: ../source/tutorials/packaging-projects.rst:520 msgid "" -"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +"Register an account on https://pypi.org - note that these are two separate " +"servers and the login details from the test server are not shared with the " +"main server." msgstr "" -#: ../source/discussions/package-formats.rst:164 +#: ../source/tutorials/packaging-projects.rst:523 msgid "" -"Wheel has a :ref:`richer file naming convention `. A " -"single wheel archive can indicate its compatibility with a number of Python " -"language versions and implementations, ABIs, and system architectures." +"Use ``twine upload dist/*`` to upload your package and enter your " +"credentials for the account you registered on the real PyPI. Now that " +"you're uploading the package in production, you don't need to specify ``--" +"repository``; the package will upload to https://pypi.org/ by default." msgstr "" -#: ../source/discussions/package-formats.rst:168 +#: ../source/tutorials/packaging-projects.rst:527 msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it." +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." msgstr "" -#: ../source/discussions/package-formats.rst:171 +#: ../source/tutorials/packaging-projects.rst:529 msgid "" -"Wheel is internally organized by `sysconfig path type `_, therefore making it " -"easier to convert to other formats." +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" msgstr "" -#: ../source/discussions/package-formats.rst:177 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"This format is email-based. Although this would be unlikely to be chosen " -"today, backwards compatibility considerations lead to it being kept as the " -"canonical format. From the user point of view, this is mostly invisible, " -"since the metadata is specified by the user in a way understood by the build " -"backend, typically ``[project]`` in ``pyproject.toml``, and translated by " -"the build backend into ``PKG-INFO``." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/glossary.rst:47 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"A :term:`Distribution ` format containing files and " -"metadata that only need to be moved to the correct location on the target " -"system, to be installed. :term:`Wheel` is such a format, whereas :term:" -"`Source Distribution ` is not, in that " -"it requires a build step before it can be installed. This format does not " -"imply that Python files have to be precompiled (:term:`Wheel` intentionally " -"does not include compiled Python files). See :ref:`package-formats` for more " -"information." +"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/glossary.rst:75 +#: ../source/tutorials/packaging-projects.rst:539 msgid "" -"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " -"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +"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/glossary.rst:239 -msgid "" -"A :term:`distribution ` format (usually generated " -"using ``python -m build --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`. See :ref:`package-formats` for more " -"information." +#: ../source/tutorials/packaging-projects.rst:547 +msgid "Notes" msgstr "" -#: ../source/glossary.rst:269 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" -"The standard :term:`Built Distribution` format. See :ref:`package-formats` " -"for more information." +"Technically, you can also create Python packages without an ``__init__.py`` " +"file, but those are called :doc:`namespace packages ` and considered an **advanced topic** (not covered in " +"this tutorial). If you are only getting started with Python packaging, it is " +"recommended to stick with *regular packages* and ``__init__.py`` (even if " +"the file is empty)." msgstr "" #, fuzzy diff --git a/locales/fa/LC_MESSAGES/messages.po b/locales/fa/LC_MESSAGES/messages.po index 21d67245c..d7ee9124b 100644 --- a/locales/fa/LC_MESSAGES/messages.po +++ b/locales/fa/LC_MESSAGES/messages.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2023-02-15 07:52+0000\n" "Last-Translator: Arsalan Dehghani \n" "Language-Team: Persian =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13517,7 +13519,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13525,24 +13527,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13550,22 +13552,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13576,65 +13578,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13642,106 +13644,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/fil/LC_MESSAGES/messages.po b/locales/fil/LC_MESSAGES/messages.po index eb6d8fd4b..9454e6403 100644 --- a/locales/fil/LC_MESSAGES/messages.po +++ b/locales/fil/LC_MESSAGES/messages.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2022-11-19 08:28+0000\n" "Last-Translator: RedFurrFox \n" "Language-Team: Filipino =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13507,7 +13509,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13515,24 +13517,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13540,22 +13542,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13566,65 +13568,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13632,106 +13634,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/fr/LC_MESSAGES/messages.po b/locales/fr/LC_MESSAGES/messages.po index 0674f8502..9e4cb1925 100644 --- a/locales/fr/LC_MESSAGES/messages.po +++ b/locales/fr/LC_MESSAGES/messages.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-01-27 05:01+0000\n" "Last-Translator: Rafael Fontenelle \n" "Language-Team: French =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13783,7 +13785,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13791,24 +13793,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13816,22 +13818,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13842,65 +13844,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13908,106 +13910,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/frc/LC_MESSAGES/messages.po b/locales/frc/LC_MESSAGES/messages.po index add4212e1..a4a7aed8e 100644 --- a/locales/frc/LC_MESSAGES/messages.po +++ b/locales/frc/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: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -2846,7 +2846,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 #: ../source/specifications/dependency-specifiers.rst:29 -#: ../source/specifications/direct-url-data-structure.rst:342 +#: ../source/specifications/direct-url-data-structure.rst:344 #: ../source/specifications/version-specifiers.rst:1067 msgid "Examples" msgstr "" @@ -11793,7 +11793,7 @@ msgstr "" #: ../source/specifications/binary-distribution-format.rst:421 #: ../source/specifications/core-metadata.rst:848 #: ../source/specifications/dependency-specifiers.rst:476 -#: ../source/specifications/direct-url-data-structure.rst:392 +#: ../source/specifications/direct-url-data-structure.rst:394 #: ../source/specifications/direct-url.rst:67 #: ../source/specifications/entry-points.rst:164 #: ../source/specifications/externally-managed-environments.rst:472 @@ -13440,10 +13440,12 @@ msgstr "" #: ../source/specifications/direct-url-data-structure.rst:61 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)." +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:63 +#: ../source/specifications/direct-url-data-structure.rst:65 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 " @@ -13451,34 +13453,34 @@ msgid "" "``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:71 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "Archive URLs" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/direct-url-data-structure.rst:75 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/direct-url-data-structure.rst:76 +#: ../source/specifications/direct-url-data-structure.rst:78 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/direct-url-data-structure.rst:79 +#: ../source/specifications/direct-url-data-structure.rst:81 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:83 +#: ../source/specifications/direct-url-data-structure.rst:85 msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/direct-url-data-structure.rst:87 msgid "" "Any hash algorithm available via :py:mod:`hashlib` (specifically any that " "can be passed to :py:func:`hashlib.new()` and do not require additional " @@ -13487,13 +13489,13 @@ msgid "" "be included. At time of writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:91 +#: ../source/specifications/direct-url-data-structure.rst:93 msgid "" "A deprecated ``hash`` key (type ``string``) MAY be present for backwards " "compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13501,7 +13503,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13509,24 +13511,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13534,22 +13536,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13560,65 +13562,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13626,106 +13628,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/gl/LC_MESSAGES/messages.po b/locales/gl/LC_MESSAGES/messages.po index b10a86443..abb18025c 100644 --- a/locales/gl/LC_MESSAGES/messages.po +++ b/locales/gl/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: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -2846,7 +2846,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 #: ../source/specifications/dependency-specifiers.rst:29 -#: ../source/specifications/direct-url-data-structure.rst:342 +#: ../source/specifications/direct-url-data-structure.rst:344 #: ../source/specifications/version-specifiers.rst:1067 msgid "Examples" msgstr "" @@ -11793,7 +11793,7 @@ msgstr "" #: ../source/specifications/binary-distribution-format.rst:421 #: ../source/specifications/core-metadata.rst:848 #: ../source/specifications/dependency-specifiers.rst:476 -#: ../source/specifications/direct-url-data-structure.rst:392 +#: ../source/specifications/direct-url-data-structure.rst:394 #: ../source/specifications/direct-url.rst:67 #: ../source/specifications/entry-points.rst:164 #: ../source/specifications/externally-managed-environments.rst:472 @@ -13440,10 +13440,12 @@ msgstr "" #: ../source/specifications/direct-url-data-structure.rst:61 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)." +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:63 +#: ../source/specifications/direct-url-data-structure.rst:65 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 " @@ -13451,34 +13453,34 @@ msgid "" "``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:71 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "Archive URLs" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/direct-url-data-structure.rst:75 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/direct-url-data-structure.rst:76 +#: ../source/specifications/direct-url-data-structure.rst:78 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/direct-url-data-structure.rst:79 +#: ../source/specifications/direct-url-data-structure.rst:81 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:83 +#: ../source/specifications/direct-url-data-structure.rst:85 msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/direct-url-data-structure.rst:87 msgid "" "Any hash algorithm available via :py:mod:`hashlib` (specifically any that " "can be passed to :py:func:`hashlib.new()` and do not require additional " @@ -13487,13 +13489,13 @@ msgid "" "be included. At time of writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:91 +#: ../source/specifications/direct-url-data-structure.rst:93 msgid "" "A deprecated ``hash`` key (type ``string``) MAY be present for backwards " "compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13501,7 +13503,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13509,24 +13511,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13534,22 +13536,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13560,65 +13562,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13626,106 +13628,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/hi/LC_MESSAGES/messages.po b/locales/hi/LC_MESSAGES/messages.po index d748f7639..91f8b0fa8 100644 --- a/locales/hi/LC_MESSAGES/messages.po +++ b/locales/hi/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: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2022-09-29 05:18+0000\n" "Last-Translator: Aryan 'Ba3a' Kumar \n" "Language-Team: Hindi =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13534,7 +13536,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13542,24 +13544,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13567,22 +13569,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13593,65 +13595,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13659,106 +13661,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/id/LC_MESSAGES/messages.po b/locales/id/LC_MESSAGES/messages.po index 54f6726c5..77b860a9c 100644 --- a/locales/id/LC_MESSAGES/messages.po +++ b/locales/id/LC_MESSAGES/messages.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-01-27 05:01+0000\n" "Last-Translator: Rafael Fontenelle \n" "Language-Team: Indonesian =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13550,7 +13552,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13558,24 +13560,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13583,22 +13585,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13609,65 +13611,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13675,106 +13677,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/ja/LC_MESSAGES/messages.po b/locales/ja/LC_MESSAGES/messages.po index 580d02903..ea5f7b18f 100644 --- a/locales/ja/LC_MESSAGES/messages.po +++ b/locales/ja/LC_MESSAGES/messages.po @@ -9,11 +9,11 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-03-07 13:21+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-04-13 10:01+0000\n" "Last-Translator: moto kawasaki \n" -"Language-Team: Japanese \n" +"Language-Team: Japanese \n" "Language: ja\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" @@ -1144,26036 +1144,25935 @@ msgstr "" "要求事項が「要約」か「具体的」かの議論についてもっと知りたい場合は、https://" "caremad.io/posts/2013/07/setup-vs-requirement/をご覧ください。" -#: ../source/discussions/pip-vs-easy-install.rst:6 -msgid "pip vs easy_install" -msgstr "pip対easy_install" +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "パッケージフォーマット" -#: ../source/discussions/pip-vs-easy-install.rst:9 +#: ../source/discussions/package-formats.rst:7 msgid "" -":ref:`easy_install `, now `deprecated`_, was released in 2004 " -"as part of :ref:`setuptools`. It was notable at the time for installing :" -"term:`packages ` from :term:`PyPI ` using requirement specifiers, and automatically installing " -"dependencies." +"This page discusses the file formats that are used to distribute Python " +"packages and the differences between them." msgstr "" -":ref:`easy_install `は、現在では`非推奨`とされていますが、2004" -"年に:ref:`setuptools`の一部として公開されました。requirementsファイルを利用し" -"て自動的に依存関係にあるパッケージも併せて:term:`PyPI `から:term:`packages `をインストールすることがで" -"きるというのは当時としては画期的でした。" +"このページでは、 Python パッケージの配布に使われるファイルフォーマット群とそ" +"の相違点について議論します。" -#: ../source/discussions/pip-vs-easy-install.rst:14 +#: ../source/discussions/package-formats.rst:10 msgid "" -":ref:`pip` came later in 2008, as alternative to :ref:`easy_install " -"`, although still largely built on top of :ref:`setuptools` " -"components. It was notable at the time for *not* installing packages as :" -"term:`Eggs ` or from :term:`Eggs ` (but rather simply as 'flat' " -"packages from :term:`sdists `), and " -"introducing the idea of :ref:`Requirements Files `, " -"which gave users the power to easily replicate environments." +"You will find files in two formats on package indices such as PyPI_: " +"**source distributions**, or **sdists** for short, and **binary " +"distributions**, commonly called **wheels**. For example, the `PyPI page " +"for pip 23.3.1 `_ lets you download two files, ``pip-23.3.1.tar." +"gz`` and ``pip-23.3.1-py3-none-any.whl``. The former is an sdist, the " +"latter is a wheel. As explained below, these serve different purposes. When " +"publishing a package on PyPI (or elsewhere), you should always upload both " +"an sdist and one or more wheel." msgstr "" -"依然として:ref:`setuptools`を部品に使ってビルドされてはいますが、:ref:" -"`easy_install `を置き換えるものとして:ref:`pip`が2008年に後から" -"やってきました。当時はパッケージを(かなり単純に:term:`sdists `から「フラット」なパッケージとしてインストールす" -"るものであって):term:`Eggs `の形でインストールするものでも、:term:`Eggs " -"`からインストールするものでも*なかった*こと、そして、簡単に環境を再現す" -"る力をユーザに与える:ref:`Requirements Files `の考え" -"方を導入したことは注目に値します。" +"PyPI_ のようなパッケージインデックス上には、２種類のフォーマットが見つかるこ" +"とでしょう: **ソースコード配布物 ** 、短縮形で " +"**sdists**と呼ばれるものと **バイナリ配布物 ** 、普通" +"は **wheels** を呼ばれるものです。例えば、 `pip 23.3.1 用の PyPI ページ `_ では、 ``pip-23.3.1.tar.gz`` と ``pip-23.3.1-py3-none-any.whl`` の二" +"つのファイルをダウンロードすることができます。前者は sdist であり、後者は " +"wheel です。下で説明するように、これらは異なった目的のために提供されていま" +"す。 PyPI (にせよ他のどこかにせよ) パッケージを公開する時は、常に sdist とひ" +"とつまたは複数の wheel の両方をアップロードするべきです。" -#: ../source/discussions/pip-vs-easy-install.rst:22 +#: ../source/discussions/package-formats.rst:21 +msgid "What is a source distribution?" +msgstr "ソースコード配布物とは何か？" + +#: ../source/discussions/package-formats.rst:23 msgid "" -"Here's a breakdown of the important differences between pip and the " -"deprecated easy_install:" +"Conceptually, a source distribution is an archive of the source code in raw " +"form. Concretely, an sdist is a ``.tar.gz`` archive containing the source " +"code plus an additional special file called ``PKG-INFO``, which holds the " +"project metadata. The presence of this file helps packaging tools to be more " +"efficient by not needing to compute the metadata themselves. The ``PKG-" +"INFO`` file follows the format specified in :ref:`core-metadata` and is not " +"intended to be written by hand [#core-metadata-format]_." msgstr "" -"pipと非推奨となったeasy_installの重要な違いをおさらいしておきましょう：" +"概念としては、ソースコード配布物は生の形のソースコードをアーカイブしたもので" +"す。具体的に言うと、sdist は、ソースコードに加えて、プロジェクトのメタデータ" +"を保持する ``PKG-INFO`` と言う名の特別なファイルをアーカイブした ``.tar.gz`` " +"ファイルです。このファイルの存在によってメタデータを自分自身で計算しなくても" +"済むようにすることでパッケージングツール群を補助しています。 ``PKG-INFO`` " +"ファイルは、 :ref:`コアとなるメタデータ ` で指定されたフォー" +"マットに従うもので、人の手で書くことが想定されていないものです [#core-" +"metadata-format]_ 。" -#: ../source/discussions/pip-vs-easy-install.rst:25 -msgid "**pip**" +#: ../source/discussions/package-formats.rst:31 +msgid "" +"You can thus inspect the contents of an sdist by unpacking it using standard " +"tools to work with tar archives, such as ``tar -xvf`` on UNIX platforms " +"(like Linux and macOS), or :ref:`the command line interface of Python's " +"tarfile module ` on any platform." msgstr "" +"従って、tar アーカイブを扱える標準的なツール、例えば UNIX プラットフォーム " +"(Linux や macOS) 上の ``tar -xvf`` や任意のプラットフォーム上の :ref:`Python " +"の tarfile モジュールのコマンドラインインターフェース ` を使ってアンパックすることで、ある sdist の内容を検査することが" +"できます。" -#: ../source/discussions/pip-vs-easy-install.rst:25 -msgid "**easy_install**" +#: ../source/discussions/package-formats.rst:36 +msgid "" +"Sdists serve several purposes in the packaging ecosystem. When :ref:`pip`, " +"the standard Python package installer, cannot find a wheel to install, it " +"will fall back on downloading a source distribution, compiling a wheel from " +"it, and installing the wheel. Furthermore, sdists are often used as the " +"package source by downstream packagers (such as Linux distributions, Conda, " +"Homebrew and MacPorts on macOS, ...), who, for various reasons, may prefer " +"them over, e.g., pulling from a Git repository." msgstr "" +"sdist は、パッケージングのエコシステムの中でいくつかの目的のために使用されま" +"す。Python パッケージインストーラの標準である :ref:`pip` がインストールするべ" +"き wheel を見つけられない時にソースコード配布物をダウンロードしてそこから " +"wheel をコンパイルし、その wheel をインストールするようにフォールバックするこ" +"とでしょう。さらに、さまざまな理由で例えば Git リポジトリからプルすることなど" +"よりも (sdist を) 好むダウンストリームパッケージ (Linux ディストリビューショ" +"ン、 Conda 、 macOS 上の Homebrew や MacPorts など ...)にとってのパッケージ" +"ソースとしてしばしば sdist が使われます。" -#: ../source/discussions/pip-vs-easy-install.rst:27 -msgid "Installs from :term:`Wheels `" -msgstr ":term:`Wheels `からのインストール" - -#: ../source/discussions/pip-vs-easy-install.rst:27 -#: ../source/discussions/pip-vs-easy-install.rst:38 -#: ../source/discussions/pip-vs-easy-install.rst:44 -#: ../source/discussions/pip-vs-easy-install.rst:48 -#: ../source/discussions/pip-vs-easy-install.rst:54 -#: ../source/discussions/pip-vs-easy-install.rst:57 -msgid "Yes" -msgstr "はい" - -#: ../source/discussions/pip-vs-easy-install.rst:27 -#: ../source/discussions/pip-vs-easy-install.rst:30 -#: ../source/discussions/pip-vs-easy-install.rst:32 -#: ../source/discussions/pip-vs-easy-install.rst:35 -#: ../source/discussions/pip-vs-easy-install.rst:38 -#: ../source/discussions/pip-vs-easy-install.rst:44 -#: ../source/discussions/pip-vs-easy-install.rst:48 -#: ../source/discussions/pip-vs-easy-install.rst:51 -#: ../source/discussions/pip-vs-easy-install.rst:54 -#: ../source/discussions/pip-vs-easy-install.rst:57 -msgid "No" -msgstr "いいえ" - -#: ../source/discussions/pip-vs-easy-install.rst:30 -msgid "Uninstall Packages" -msgstr "パッケージのアンインストール" - -#: ../source/discussions/pip-vs-easy-install.rst:30 -msgid "Yes (``python -m pip uninstall``)" -msgstr "はい (``python -m pip uninstall``)" - -#: ../source/discussions/pip-vs-easy-install.rst:32 -msgid "Dependency Overrides" -msgstr "依存関係を上書きする" - -#: ../source/discussions/pip-vs-easy-install.rst:32 -msgid "Yes (:ref:`Requirements Files `)" -msgstr "はい (:ref:`Requirementsファイル `" - -#: ../source/discussions/pip-vs-easy-install.rst:35 -msgid "List Installed Packages" -msgstr "インストールされたパッケージのリスト" - -#: ../source/discussions/pip-vs-easy-install.rst:35 -msgid "Yes (``python -m pip list`` and ``python -m pip freeze``)" -msgstr "はい (``python -m pip list`` and ``python -m pip freeze``)" - -#: ../source/discussions/pip-vs-easy-install.rst:38 -msgid ":pep:`438` Support" -msgstr ":pep:`438` サポート" - -#: ../source/discussions/pip-vs-easy-install.rst:41 -msgid "Installation format" -msgstr "インストールフォーマット" - -#: ../source/discussions/pip-vs-easy-install.rst:41 -msgid "'Flat' packages with :file:`egg-info` metadata." -msgstr ":file:`egg-info`のメタデータを伴った「フラット」なパッケージ。" - -#: ../source/discussions/pip-vs-easy-install.rst:41 -msgid "Encapsulated Egg format" -msgstr "カプセル化されたEggフォーマット" - -#: ../source/discussions/pip-vs-easy-install.rst:44 -msgid "sys.path modification" -msgstr "sys.pathの変更" - -#: ../source/discussions/pip-vs-easy-install.rst:48 -msgid "Installs from :term:`Eggs `" -msgstr ":term:`Eggs `からのインストール" - -#: ../source/discussions/pip-vs-easy-install.rst:51 -msgid "`pylauncher support`_" -msgstr "`pylauncherサポート `_" - -#: ../source/discussions/pip-vs-easy-install.rst:51 -msgid "Yes [1]_" -msgstr "はい [1]_" - -#: ../source/discussions/pip-vs-easy-install.rst:54 -msgid ":ref:`Multi-version Installs`" -msgstr ":ref:`複数バージョンのインストール `" - -#: ../source/discussions/pip-vs-easy-install.rst:57 -msgid "Exclude scripts during install" -msgstr "インストール中にスクリプトを除外する" - -#: ../source/discussions/pip-vs-easy-install.rst:60 -msgid "per project index" -msgstr "プロジェクトごとの索引" - -#: ../source/discussions/pip-vs-easy-install.rst:60 -msgid "Only in virtualenv" -msgstr "virtualenvの中のみ" - -#: ../source/discussions/pip-vs-easy-install.rst:60 -msgid "Yes, via setup.cfg" -msgstr "はい、setup.cfgを通じて" +#: ../source/discussions/package-formats.rst:44 +msgid "" +"A source distribution is recognized by its file name, which has the form :" +"samp:`{package_name}-{version}.tar.gz`, e.g., ``pip-23.3.1.tar.gz``." +msgstr "" +"ソースコード配布物は、 :samp:`{package_name}-{version}.tar.gz` の形、例えば " +"``pip-23.3.1.tar.gz`` のファイル名で識別されます。" -#: ../source/discussions/pip-vs-easy-install.rst:68 +#: ../source/discussions/package-formats.rst:50 msgid "" -"https://setuptools.readthedocs.io/en/latest/deprecated/easy_install." -"html#natural-script-launcher" +"If you want technical details on the sdist format, read the :ref:`sdist " +"specification `." msgstr "" -"https://setuptools.readthedocs.io/en/latest/deprecated/easy_install." -"html#natural-script-launcher" +"sdist 形式の技術的な詳細を知りたければ、 :ref:`sdist 仕様 ` を見てください。" -#: ../source/discussions/setup-py-deprecated.rst:6 -msgid "Is ``setup.py`` deprecated?" -msgstr "``setup.py`` は非推奨になりましたか？" +#: ../source/discussions/package-formats.rst:55 +msgid "What is a wheel?" +msgstr "wheel とは何か？" -#: ../source/discussions/setup-py-deprecated.rst:8 -msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +#: ../source/discussions/package-formats.rst:57 +msgid "" +"Conceptually, a wheel contains exactly the files that need to be copied when " +"installing the package." msgstr "" -"いいえ、 :term:`setup.py` および :ref:`setuptools` は非推奨にはなっていませ" -"ん。" +"概念としては、 wheel は、パッケージをインストールする際にコピーされる必要のあ" +"るファイル群をそのまま含んでいるものです。" -#: ../source/discussions/setup-py-deprecated.rst:10 +#: ../source/discussions/package-formats.rst:60 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:" -"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." +"There is a big difference between sdists and wheels for packages with :term:" +"`extension modules `, written in compiled languages like " +"C, C++ and Rust, which need to be compiled into platform-dependent machine " +"code. With these packages, wheels do not contain source code (like C source " +"files) but compiled, executable code (like ``.so`` files on Linux or DLLs on " +"Windows)." msgstr "" -"Setuptools は、 :term:`ビルドバックエンド ` として Python のプ" -"ロジェクトをパッケージングすることに完璧に使用可能です。そして、 :file:" -"`setup.py` は、例えば *TOML* の代わりにたまたま Python で書かれている :ref:" -"`setuptools` 向けの正当な設定ファイルです (*nox* とその設定ファイルである :" -"file:`nox.filepy` や *pytest* と :file:`conftest.py` のような他のツール類で" -"も、よく似たパターンが使われています)。" +"プラットフォームに依存した機械語にコンパイルする必要がある C や C++ や Rust " +"のようなコンパイル言語で書かれた :term:`拡張モジュール ` を" +"伴うパッケージにおいては、sdist と wheel の間には大きな違いがあります。このよ" +"うなパッケージでは、 wheel は (C言語のソースのような) ソースコードを内包して" +"おらず、代わりに (Linux における ``.so`` ファイルや Windows における DLL のよ" +"うな) コンパイル済みで実行可能なコードを含んでいます。" -#: ../source/discussions/setup-py-deprecated.rst:18 +#: ../source/discussions/package-formats.rst:66 msgid "" -"However, ``python setup.py`` and the use of :file:`setup.py` as a command " -"line tool are deprecated." +"Furthermore, while there is only one sdist per version of a project, there " +"may be many wheels. Again, this is most relevant in the context of extension " +"modules. The compiled code of an extension module is tied to an operating " +"system and processor architecture, and often also to the version of the " +"Python interpreter (unless the :ref:`Python stable ABI ` " +"is used)." msgstr "" -"しかしながら、 ``python setup.py`` および :file:`setup.py` をコマンドライン" -"ツールとして使うことは非推奨になりました。" +"さらにまた、あるバージョンのプロジェクトには sdist がひとつしか存在しない一方" +"で、wheel はたくさんあるかもしれません。繰り返しになりますが、これは拡張モ" +"ジュールの文脈でもっとも有りがちなことです。拡張モジュールのコンパイル済みの" +"コードはオペレーティングシステムとプロセッサーアーキテクチャに、また、 (:ref:" +"`Python stable ABI ` を使っていなければ) しばしば Python " +"インタープリタのバージョンに紐付いています。" -#: ../source/discussions/setup-py-deprecated.rst:21 +#: ../source/discussions/package-formats.rst:72 msgid "" -"This means that commands such as the following **MUST NOT** be run anymore:" +"For pure-Python packages, the difference between sdists and wheels is less " +"marked. There is normally one single wheel, for all platforms and Python " +"versions. Python is an interpreted language, which does not need ahead-of-" +"time compilation, so wheels contain ``.py`` files just like sdists." msgstr "" -"その意味するところは、次のようなコマンドを実行することはもはや **許されない" -"** ということです:" - -#: ../source/discussions/setup-py-deprecated.rst:23 -#: ../source/discussions/setup-py-deprecated.rst:35 -#: ../source/guides/modernize-setup-py-project.rst:32 -msgid "``python setup.py install``" -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 "``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 -msgid "``python setup.py sdist``" -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 "``python setup.py bdist_wheel``" - -#: ../source/discussions/setup-py-deprecated.rst:30 -msgid "What commands should be used instead?" -msgstr "代わりにどのようなコマンドを使うべきでしょうか？" - -#: ../source/discussions/setup-py-deprecated.rst:33 -#: ../source/guides/modernize-setup-py-project.rst:30 -msgid "Deprecated" -msgstr "非推奨" - -#: ../source/discussions/setup-py-deprecated.rst:33 -#: ../source/guides/modernize-setup-py-project.rst:30 -msgid "Recommendation" -msgstr "推奨事項" - -#: ../source/discussions/setup-py-deprecated.rst:35 -#: ../source/guides/modernize-setup-py-project.rst:32 -msgid "``python -m pip install .``" -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 "``python -m pip install --editable .``" - -#: ../source/discussions/setup-py-deprecated.rst:39 -msgid "``python -m build`` [#needs-build]_" -msgstr "``python -m build`` [#needs-build]_" +"純 Python のパッケージでは、 sdist と wheel の差異はあまり顕著ではありませ" +"ん。普通は、あらゆるプラットフォームと Python のバージョン向けに wheel がたっ" +"たひとつ存在します。 Python はインタープリタ言語であり、事前にコンパイルして" +"おく必要がなく、それゆえに wheel は sdist と同様に ``.py`` ファイル群を内包し" +"ているのです。" -#: ../source/discussions/setup-py-deprecated.rst:45 +#: ../source/discussions/package-formats.rst:77 msgid "" -"This requires the :ref:`build` dependency. It is recommended to always build " -"and publish both the source distribution and wheel of a project, which is " -"what ``python -m build`` does. If necessary the ``--sdist`` and ``--wheel`` " -"options can be used to generate only one or the other." +"If you are wondering about ``.pyc`` bytecode files: they are not included in " +"wheels, since they are cheap to generate, and including them would " +"unnecessarily force a huge number of packages to distribute one wheel per " +"Python version instead of one single wheel. Instead, installers like :ref:" +"`pip` generate them while installing the package." msgstr "" -"これは、:ref:`build` の依存関係を要求します。 ``python -m build`` を実行すれ" -"ばそうなりますが、プロジェクトにおいては常にソースコード配布物とwheelの両方を" -"公開することを推奨します。もし必要であれば、いずれか片方を生成するのに ``--" -"sdist`` や ``--wheel`` のオプションを使うことができます。" +"``.pyc`` バイトコードファイル群: これらは wheel には含まれていませんが、これ" +"らについて不思議に思っているなら、これらは安価に生成することができ、また、も" +"しこれをパッケージに含めるとすれば、単一の wheel を配布する代わりに、Python " +"のバージョン毎に巨大な数のパッケージを配布するという不必要なことを強いられる" +"ことになるでしょう。代わりに、 :ref:`pip` のようなインストーラがインストール" +"中に生成しています。" -#: ../source/discussions/setup-py-deprecated.rst:52 +#: ../source/discussions/package-formats.rst:83 msgid "" -"In order to install a setuptools based project, it was common to run :file:" -"`setup.py`'s ``install`` command such as: ``python setup.py install``. " -"Nowadays, the recommended method is to use :ref:`pip` directly with a " -"command like this one: ``python -m pip install .``. Where the dot ``.`` is " -"actually a file system path, it is the path notation for the current " -"directory. Indeed, *pip* accepts a path to a project's source tree directory " -"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``." +"With that being said, there are still important differences between sdists " +"and wheels, even for pure Python projects. Wheels are meant to contain " +"exactly what is to be installed, and nothing more. In particular, wheels " +"should never include tests and documentation, while sdists commonly do. " +"Also, the wheel format is more complex than sdist. For example, it includes " +"a special file -- called ``RECORD`` -- that lists all files in the wheel " +"along with a hash of their content, as a safety check of the download's " +"integrity." msgstr "" -"setuptools ベースのプロジェクトをインストールするためには、``python setup.py " -"install`` のように :file:`setup.py` の ``install`` コマンドを使うことが普通で" -"した。今日では、``python -m pip install .`` のように :ref:`pip` を直接に使う" -"方法が推奨されています。ここでドット ``.`` は、実際にはファイルシステム上のパ" -"スなので、これはカレントディレクトリを示すパス表現です。なんと、 *pip* は " -"``install`` サブコマンドへの引数の形で、ローカルのファイルシステム上のパスを" -"プロジェクトのソースコードツリーを置くべき場所として受け付けるのです。そうい" -"うことですから、これもまた正当なコマンドということになります: ``python -m " -"pip install path/to/project``。" -#: ../source/discussions/setup-py-deprecated.rst:65 +#: ../source/discussions/package-formats.rst:91 msgid "" -"As for the installation in *develop* mode aka *editable* mode, instead of " -"``python setup.py develop`` one can use the ``--editable`` option of pip's " -"*install* sub-command: ``python -m pip install --editable .``." +"At a glance, you might wonder if wheels are really needed for \"plain and " +"basic\" pure Python projects. Keep in mind that due to the flexibility of " +"sdists, installers like pip cannot install from sdists directly -- they need " +"to first build a wheel, by invoking the :term:`build backend` that the sdist " +"specifies (the build backend may do all sorts of transformations while " +"building the wheel, such as compiling C extensions). For this reason, even " +"for a pure Python project, you should always upload *both* an sdist and a " +"wheel to PyPI or other package indices. This makes installation much faster " +"for your users, since a wheel is directly installable. By only including " +"files that must be installed, wheels also make for smaller downloads." msgstr "" -"*編集可能 * モードとしても知られる *開発 * モードでのイン" -"ストールのためには、 ``python setup.py develop`` の代わりに pip の *install* " -"サブコマンドの ``--editable`` オプションを使うことができます: ``python -m " -"pip install --editable .``。" -#: ../source/discussions/setup-py-deprecated.rst:70 +#: ../source/discussions/package-formats.rst:102 msgid "" -"One recommended, simple, and straightforward method of building :term:" -"`source distributions ` and :term:" -"`wheels ` is to use the :ref:`build` tool with a command like " -"``python -m build`` which triggers the generation of both distribution " -"formats. If necessary the ``--sdist`` and ``--wheel`` options can be used to " -"generate only one or the other. Note that the build tool needs to be " -"installed separately." +"On the technical level, a wheel is a ZIP archive (unlike sdists which are " +"TAR archives). You can inspect its contents by unpacking it as a normal ZIP " +"archive, e.g., using ``unzip`` on UNIX platforms like Linux and macOS, " +"``Expand-Archive`` in Powershell on Windows, or :ref:`the command line " +"interface of Python's zipfile module `. This can " +"be very useful to check that the wheel includes all the files you need it to." msgstr "" -":term:`ソースコード配布物 ` および :term:" -"`wheels ` をビルドする方法で推奨されていて単純かつ直截なひとつのやり方" -"は、 :ref:`build` ツールを ``python -m build`` のようなコマンドから使って両方" -"の配布物フォーマットの生成を開始することです。いずれか片方の配布物だけを生成" -"するのであれば、必要に応じて ``--sdist`` や ``--wheel`` のオプションを使うこ" -"とができます。build ツールは個別にインストールする必要があることに注意してく" -"ださい。" -#: ../source/discussions/setup-py-deprecated.rst:80 +#: ../source/discussions/package-formats.rst:109 msgid "" -"The command ``python setup.py install`` was deprecated in setuptools version " -"*58.3.0*." +"Inside a wheel, you will find the package's files, plus an additional " +"directory called :samp:`{package_name}-{version}.dist-info`. This directory " +"contains various files, including a ``METADATA`` file which is the " +"equivalent of ``PKG-INFO`` in sdists, as well as ``RECORD``. This can be " +"useful to ensure no files are missing from your wheels." msgstr "" -"コマンド ``python setup.py install`` は、setuptools のバージョン *58.3.0* で" -"非推奨になりました。" -#: ../source/discussions/setup-py-deprecated.rst:85 -msgid "What about other commands?" -msgstr "他のコマンドについてはどうでしょうか？" +#: ../source/discussions/package-formats.rst:115 +msgid "" +"The file name of a wheel (ignoring some rarely used features) looks like " +"this: :samp:`{package_name}-{version}-{python_tag}-{abi_tag}-{platform_tag}." +"whl`. This naming convention identifies which platforms and Python versions " +"the wheel is compatible with. For example, the name ``pip-23.3.1-py3-none-" +"any.whl`` means that:" +msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:87 -msgid "What are some replacements for the other ``python setup.py`` commands?" -msgstr "他の ``python setup.py`` コマンドを置き換えるものは何でしょうか？" +#: ../source/discussions/package-formats.rst:121 +msgid "" +"(``py3``) This wheel can be installed on any implementation of Python 3, " +"whether CPython, the most widely used Python implementation, or an " +"alternative implementation like PyPy_;" +msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:91 -msgid "``python setup.py test``" -msgstr "``python setup.py test``" +#: ../source/discussions/package-formats.rst:124 +msgid "(``none``) It does not depend on the Python version;" +msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:93 -msgid "The recommendation is to use a test runner such as pytest_." -msgstr "推奨されるものは、pytest_ のようなテストランナーを使うことです。" +#: ../source/discussions/package-formats.rst:125 +msgid "(``any``) It does not depend on the platform." +msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:99 +#: ../source/discussions/package-formats.rst:127 msgid "" -"``python setup.py check``, ``python setup.py register``, and ``python setup." -"py upload``" +"The pattern ``py3-none-any`` is common for pure Python projects. Packages " +"with extension modules typically ship multiple wheels with more complex tags." 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 "信頼されている代替物は :ref:`twine` です:" +#: ../source/discussions/package-formats.rst:130 +msgid "" +"All technical details on the wheel format can be found in the :ref:`wheel " +"specification `." +msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check --strict dist/*``" -msgstr "``python -m twine check --strict dist/*``" +#: ../source/discussions/package-formats.rst:138 +#, fuzzy +msgid "What about eggs?" +msgstr "これは何..." -#: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" -msgstr "``python -m twine register dist/*.whl`` [#not-pypi]_" +#: ../source/discussions/package-formats.rst:140 +msgid "" +"\"Egg\" is an old package format that has been replaced with the wheel " +"format. It should not be used anymore. Since August 2023, PyPI `rejects egg " +"uploads `_." +msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload dist/*``" -msgstr "``python -m twine upload dist/*``" +#: ../source/discussions/package-formats.rst:144 +#, fuzzy +msgid "Here's a breakdown of the important differences between wheel and egg." +msgstr ":term:`Wheel`と :term:`Egg`の重要な差異について以下にまとめます。" -#: ../source/discussions/setup-py-deprecated.rst:107 +#: ../source/discussions/package-formats.rst:146 +#, fuzzy msgid "" -"Not necessary, nor supported on :term:`PyPI `. " -"But might be necessary on other :term:`package indexes ` (for " -"example :ref:`devpi`)." +"The egg format was introduced by :ref:`setuptools` in 2004, whereas the " +"wheel format was introduced by :pep:`427` in 2012." msgstr "" -"必ずしもそうではなく、 :term:`PyPI ` でもサポー" -"トされていません。しかし、(例えば :ref:`devpi` のような) 他の :term:`パッケー" -"ジインデックス ` では必要になるかもしれません。" - -#: ../source/discussions/setup-py-deprecated.rst:112 -msgid "``python setup.py --version``" -msgstr "``python setup.py --version``" +":term:`Egg`のフォーマットは、2004年に:ref:`setuptools`によって、また、:term:" +"`Wheel`のフォーマットは2012年に:pep:`427`によって導入されました。" -#: ../source/discussions/setup-py-deprecated.rst:114 +#: ../source/discussions/package-formats.rst:149 +#, fuzzy msgid "" -"A possible replacement solution (among others) is to rely on setuptools-scm_:" +"Wheel has an :doc:`official standard specification `. Egg did not." msgstr "" -"実行可能な代替案は (他にもありますが) setuptools-scm_ に頼ることでしょう:" +":term:`Wheel`には :doc:`公式の標準仕様 ` が存在します。 :term:`Egg`には対応するPEPがありません。" -#: ../source/discussions/setup-py-deprecated.rst:116 -msgid "``python -m setuptools_scm``" -msgstr "``python -m setuptools_scm``" +#: ../source/discussions/package-formats.rst:152 +#, fuzzy +msgid "" +"Wheel is a :term:`distribution ` format, i.e a " +"packaging format. [#wheel-importable]_ Egg was both a distribution format " +"and a runtime installation format (if left zipped), and was designed to be " +"importable." +msgstr "" +":term:`Wheel`は :term:`配布物 `のフォーマット、つまり、" +"パッケージのフォーマットです。[1]_ :term:`Egg`は配布物のフォーマットでもあ" +"り、かつ、(もし圧縮されたままであれば)実行時のインストールフォーマットであっ" +"てimportができるように設計されています。" -#: ../source/discussions/setup-py-deprecated.rst:122 -msgid "Remaining commands" -msgstr "残りのコマンド群" +#: ../source/discussions/package-formats.rst:156 +#, fuzzy +msgid "" +"Wheel archives do not include ``.pyc`` files. Therefore, when the " +"distribution only contains Python files (i.e. no compiled extensions), and " +"is compatible with Python 2 and 3, it's possible for a wheel to be " +"\"universal\", similar to an :term:`sdist `." +msgstr "" +":term:`Wheel`形式のファイルには.pycファイルが含まれていません。従って、配布物" +"には(コンパイル済のファイル抜きの)Pythonファイルのみ(含み、Pythonのバージョン" +"2と3で使用可能ですので、 :term:`sdist `と" +"同様にwheelは「汎用」であると言うことができます。" -#: ../source/discussions/setup-py-deprecated.rst:124 +#: ../source/discussions/package-formats.rst:161 +#, fuzzy msgid "" -"This guide does not make suggestions of replacement solutions for those " -"commands:" -msgstr "このガイド文書では、それらコマンド群の代替案について示唆しません:" +"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +msgstr "" +":term:`Wheel`は :pep:`PEP376-compliant <376>`に従って ``.dist-info`` ディレク" +"トリを用います。Eggは ``.egg-info`` を用います。" -#: ../source/discussions/setup-py-deprecated.rst:129 -msgid "``alias``" -msgstr "``alias``" +#: ../source/discussions/package-formats.rst:164 +#, fuzzy +msgid "" +"Wheel has a :ref:`richer file naming convention `. A " +"single wheel archive can indicate its compatibility with a number of Python " +"language versions and implementations, ABIs, and system architectures." +msgstr "" +":term:`Wheel`には:pep:`richer file naming convention <425>`が存在します。単独" +"のwheelアーカイブはPython言語のバージョンや実装、ABI、そしてシステムのアーキ" +"テクチャとの互換性を表示することができます。" -#: ../source/discussions/setup-py-deprecated.rst:130 -msgid "``bdist``" -msgstr "``bdist``" +#: ../source/discussions/package-formats.rst:168 +#, fuzzy +msgid "" +"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/setup-py-deprecated.rst:131 -msgid "``bdist_dumb``" -msgstr "``bdist_dumb``" +#: ../source/discussions/package-formats.rst:171 +#, fuzzy +msgid "" +"Wheel is internally organized by `sysconfig path type `_, therefore making it " +"easier to convert to other formats." +msgstr "" +":term:`Wheel`は内部では`sysconfigパスの型 `_で整理されているので、他のフォーマットに" +"変換するのがより簡単になっています。" -#: ../source/discussions/setup-py-deprecated.rst:132 -msgid "``bdist_egg``" -msgstr "``bdist_egg``" +#: ../source/discussions/package-formats.rst:177 +msgid "" +"This format is email-based. Although this would be unlikely to be chosen " +"today, backwards compatibility considerations lead to it being kept as the " +"canonical format. From the user point of view, this is mostly invisible, " +"since the metadata is specified by the user in a way understood by the build " +"backend, typically ``[project]`` in ``pyproject.toml``, and translated by " +"the build backend into ``PKG-INFO``." +msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 -msgid "``bdist_rpm``" -msgstr "``bdist_rpm``" +#: ../source/discussions/package-formats.rst:184 +msgid "" +"Circumstantially, in some cases, wheels can be used as an importable runtime " +"format, although :ref:`this is not officially supported at this time `." +msgstr "" +"状況としては、 :ref:`現時点で公式にはサポートされていません ` が、 一部のケースで wheel ファイルをイン" +"ポート可能な稼働時(runtime)フォーマットとして使うことが可能です。" -#: ../source/discussions/setup-py-deprecated.rst:134 -msgid "``build``" -msgstr "``build``" +#: ../source/discussions/pip-vs-easy-install.rst:6 +msgid "pip vs easy_install" +msgstr "pip対easy_install" -#: ../source/discussions/setup-py-deprecated.rst:135 -msgid "``build_clib``" -msgstr "``build_clib``" +#: ../source/discussions/pip-vs-easy-install.rst:9 +msgid "" +":ref:`easy_install `, now `deprecated`_, was released in 2004 " +"as part of :ref:`setuptools`. It was notable at the time for installing :" +"term:`packages ` from :term:`PyPI ` using requirement specifiers, and automatically installing " +"dependencies." +msgstr "" +":ref:`easy_install `は、現在では`非推奨`とされていますが、2004" +"年に:ref:`setuptools`の一部として公開されました。requirementsファイルを利用し" +"て自動的に依存関係にあるパッケージも併せて:term:`PyPI `から:term:`packages `をインストールすることがで" +"きるというのは当時としては画期的でした。" -#: ../source/discussions/setup-py-deprecated.rst:136 -msgid "``build_ext``" -msgstr "``build_ext``" +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as alternative to :ref:`easy_install " +"`, although still largely built on top of :ref:`setuptools` " +"components. It was notable at the time for *not* installing packages as :" +"term:`Eggs ` or from :term:`Eggs ` (but rather simply as 'flat' " +"packages from :term:`sdists `), and " +"introducing the idea of :ref:`Requirements Files `, " +"which gave users the power to easily replicate environments." +msgstr "" +"依然として:ref:`setuptools`を部品に使ってビルドされてはいますが、:ref:" +"`easy_install `を置き換えるものとして:ref:`pip`が2008年に後から" +"やってきました。当時はパッケージを(かなり単純に:term:`sdists `から「フラット」なパッケージとしてインストールす" +"るものであって):term:`Eggs `の形でインストールするものでも、:term:`Eggs " +"`からインストールするものでも*なかった*こと、そして、簡単に環境を再現す" +"る力をユーザに与える:ref:`Requirements Files `の考え" +"方を導入したことは注目に値します。" -#: ../source/discussions/setup-py-deprecated.rst:137 -msgid "``build_py``" -msgstr "``build_py``" +#: ../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 "" +"pipと非推奨となったeasy_installの重要な違いをおさらいしておきましょう：" -#: ../source/discussions/setup-py-deprecated.rst:138 -msgid "``build_scripts``" -msgstr "``build_scripts``" +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 -msgid "``clean``" -msgstr "``clean``" +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 -msgid "``dist_info``" -msgstr "``dist_info``" +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr ":term:`Wheels `からのインストール" -#: ../source/discussions/setup-py-deprecated.rst:141 -msgid "``easy_install``" -msgstr "``easy_install``" +#: ../source/discussions/pip-vs-easy-install.rst:27 +#: ../source/discussions/pip-vs-easy-install.rst:38 +#: ../source/discussions/pip-vs-easy-install.rst:44 +#: ../source/discussions/pip-vs-easy-install.rst:48 +#: ../source/discussions/pip-vs-easy-install.rst:54 +#: ../source/discussions/pip-vs-easy-install.rst:57 +msgid "Yes" +msgstr "はい" -#: ../source/discussions/setup-py-deprecated.rst:142 -msgid "``editable_wheel``" -msgstr "``editable_wheel``" +#: ../source/discussions/pip-vs-easy-install.rst:27 +#: ../source/discussions/pip-vs-easy-install.rst:30 +#: ../source/discussions/pip-vs-easy-install.rst:32 +#: ../source/discussions/pip-vs-easy-install.rst:35 +#: ../source/discussions/pip-vs-easy-install.rst:38 +#: ../source/discussions/pip-vs-easy-install.rst:44 +#: ../source/discussions/pip-vs-easy-install.rst:48 +#: ../source/discussions/pip-vs-easy-install.rst:51 +#: ../source/discussions/pip-vs-easy-install.rst:54 +#: ../source/discussions/pip-vs-easy-install.rst:57 +msgid "No" +msgstr "いいえ" -#: ../source/discussions/setup-py-deprecated.rst:143 -msgid "``egg_info``" -msgstr "``egg_info``" +#: ../source/discussions/pip-vs-easy-install.rst:30 +msgid "Uninstall Packages" +msgstr "パッケージのアンインストール" -#: ../source/discussions/setup-py-deprecated.rst:144 -msgid "``install``" -msgstr "``install``" +#: ../source/discussions/pip-vs-easy-install.rst:30 +msgid "Yes (``python -m pip uninstall``)" +msgstr "はい (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:145 -msgid "``install_data``" -msgstr "``install_data``" +#: ../source/discussions/pip-vs-easy-install.rst:32 +msgid "Dependency Overrides" +msgstr "依存関係を上書きする" -#: ../source/discussions/setup-py-deprecated.rst:146 -msgid "``install_egg_info``" -msgstr "``install_egg_info``" +#: ../source/discussions/pip-vs-easy-install.rst:32 +msgid "Yes (:ref:`Requirements Files `)" +msgstr "はい (:ref:`Requirementsファイル `" -#: ../source/discussions/setup-py-deprecated.rst:147 -msgid "``install_headers``" -msgstr "``install_headers``" +#: ../source/discussions/pip-vs-easy-install.rst:35 +msgid "List Installed Packages" +msgstr "インストールされたパッケージのリスト" -#: ../source/discussions/setup-py-deprecated.rst:148 -msgid "``install_lib``" -msgstr "``install_lib``" +#: ../source/discussions/pip-vs-easy-install.rst:35 +msgid "Yes (``python -m pip list`` and ``python -m pip freeze``)" +msgstr "はい (``python -m pip list`` and ``python -m pip freeze``)" -#: ../source/discussions/setup-py-deprecated.rst:149 -msgid "``install_scripts``" -msgstr "``install_scripts``" +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr ":pep:`438` サポート" -#: ../source/discussions/setup-py-deprecated.rst:150 -msgid "``rotate``" -msgstr "``rotate``" +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Installation format" +msgstr "インストールフォーマット" -#: ../source/discussions/setup-py-deprecated.rst:151 -msgid "``saveopts``" -msgstr "``saveopts``" +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "'Flat' packages with :file:`egg-info` metadata." +msgstr ":file:`egg-info`のメタデータを伴った「フラット」なパッケージ。" -#: ../source/discussions/setup-py-deprecated.rst:152 -msgid "``setopt``" -msgstr "``setopt``" +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "カプセル化されたEggフォーマット" -#: ../source/discussions/setup-py-deprecated.rst:153 -msgid "``upload_docs``" -msgstr "``upload_docs``" +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "sys.pathの変更" -#: ../source/discussions/setup-py-deprecated.rst:157 -msgid "What about custom commands?" -msgstr "カスタムコマンドについてはどうでしょうか？" +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr ":term:`Eggs `からのインストール" -#: ../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/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "`pylauncherサポート `_" -#: ../source/discussions/setup-py-deprecated.rst:167 -msgid "What about custom build steps?" -msgstr "カスタムビルドステップについてはどうでしょうか？" +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "はい [1]_" -#: ../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/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr ":ref:`複数バージョンのインストール `" -#: ../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/pip-vs-easy-install.rst:57 +msgid "Exclude scripts during install" +msgstr "インストール中にスクリプトを除外する" -#: ../source/discussions/setup-py-deprecated.rst:178 +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "per project index" +msgstr "プロジェクトごとの索引" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Only in virtualenv" +msgstr "virtualenvの中のみ" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "はい、setup.cfgを通じて" + +#: ../source/discussions/pip-vs-easy-install.rst:68 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`." +"https://setuptools.readthedocs.io/en/latest/deprecated/easy_install." +"html#natural-script-launcher" msgstr "" -":file:`setup.py` を実行可能なスクリプトとして使うことは非推奨になりましたが、" -"しかし、setuptools に対する設定ファイルとして使うことは完全に正当です。:file:" -"`setup.py` を修正する必要はないでしょう。" +"https://setuptools.readthedocs.io/en/latest/deprecated/easy_install." +"html#natural-script-launcher" -#: ../source/discussions/setup-py-deprecated.rst:184 -msgid "Is ``pyproject.toml`` mandatory?" -msgstr "``pyproject.toml`` は必須ですか？" +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "``setup.py`` は非推奨になりましたか？" -#: ../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:" +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." msgstr "" -"技術的には無くてはならないというわけではありませんが、プロジェクトがそのソー" -"スコードツリーのルート部分に :file:`pyproject.toml` ファイルを持つことは **強" -"く推奨** されています:" +"いいえ、 :term:`setup.py` および :ref:`setuptools` は非推奨にはなっていませ" +"ん。" -#: ../source/discussions/setup-py-deprecated.rst:197 +#: ../source/discussions/setup-py-deprecated.rst:10 msgid "" -"The guide :ref:`modernize-setup-py-project` has more details about this." +"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:" +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" -"これについては、説明文書の :ref:`setup.py 近代化プロジェクト ` にもっと詳しい説明があります。" +"Setuptools は、 :term:`ビルドバックエンド ` として Python のプ" +"ロジェクトをパッケージングすることに完璧に使用可能です。そして、 :file:" +"`setup.py` は、例えば *TOML* の代わりにたまたま Python で書かれている :ref:" +"`setuptools` 向けの正当な設定ファイルです (*nox* とその設定ファイルである :" +"file:`nox.filepy` や *pytest* と :file:`conftest.py` のような他のツール類で" +"も、よく似たパターンが使われています)。" -#: ../source/discussions/setup-py-deprecated.rst:199 +#: ../source/discussions/setup-py-deprecated.rst:18 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." +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." msgstr "" -":file:`pyproject.toml` ファイルとその ``[build-system]`` テーブルが存在しない" -"場合、 :term:`ビルドフロントエンド ` にとって標準的なフォール" -"バックの振る舞いは、 :term:`ビルドバックエンド ` が " -"setuptools であると仮定することです。" - -#: ../source/discussions/setup-py-deprecated.rst:205 -msgid "Why? What does it all mean?" -msgstr "どうして？一体全体どういうこと？" +"しかしながら、 ``python setup.py`` および :file:`setup.py` をコマンドライン" +"ツールとして使うことは非推奨になりました。" -#: ../source/discussions/setup-py-deprecated.rst:207 +#: ../source/discussions/setup-py-deprecated.rst:21 msgid "" -"One way to look at it is that the scope of setuptools has now been reduced " -"to the role of a build backend." +"This means that commands such as the following **MUST NOT** be run anymore:" msgstr "" -"ひとつの見方は、setuptools のスコープが、いまや、ビルドバックエンドの役割に限" -"定されているということです。" +"その意味するところは、次のようなコマンドを実行することはもはや **許されない" +"** ということです:" -#: ../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:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "``python setup.py install``" -#: ../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:24 +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python setup.py develop``" +msgstr "``python setup.py develop``" -#: ../source/discussions/setup-py-deprecated.rst:216 -msgid ":doc:`setuptools:deprecated/commands`" -msgstr ":doc:`setuptools:deprecated/commands`" +#: ../source/discussions/setup-py-deprecated.rst:25 +#: ../source/discussions/setup-py-deprecated.rst:39 +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python setup.py sdist``" +msgstr "``python setup.py sdist``" -#: ../source/discussions/src-layout-vs-flat-layout.rst:5 -msgid "src layout vs flat layout" -msgstr "src レイアウト対フラットレイアウト" +#: ../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 "``python setup.py bdist_wheel``" -#: ../source/discussions/src-layout-vs-flat-layout.rst:7 -msgid "" -"The \"flat layout\" refers to organising a project's files in a folder or " -"repository, such that the various configuration files and :term:`import " -"packages ` are all in the top-level directory." -msgstr "" -"「フラットレイアウト」とは、さまざまな設定ファイルや :term:`インポートパッ" -"ケージ ` をすべてトップレベルのディレクトリに置くようなやり方" -"で、プロジェクトのファイル群をひとつのフォルダまたはリポジトリに配置すること" -"です。" +#: ../source/discussions/setup-py-deprecated.rst:30 +msgid "What commands should be used instead?" +msgstr "代わりにどのようなコマンドを使うべきでしょうか？" -#: ../source/discussions/src-layout-vs-flat-layout.rst:25 -msgid "" -"The \"src layout\" deviates from the flat layout by moving the code that is " -"intended to be importable (i.e. ``import awesome_package``, also known as :" -"term:`import packages `) into a subdirectory. This " -"subdirectory is typically named ``src/``, hence \"src layout\"." -msgstr "" -"「src レイアウト」は、インポート可能 (すなわち ``import awesome_package`` 、" -"別名 :term:`インポートパッケージ `) にするつもりのソースコー" -"ドをサブディレクトリに置く点でフラットレイアウトとは異なります。このサブディ" -"レクトリは、典型的には ``src/`` と命名されるので、「src レイアウト」と呼ばれ" -"るのです。" +#: ../source/discussions/setup-py-deprecated.rst:33 +#: ../source/guides/modernize-setup-py-project.rst:30 +msgid "Deprecated" +msgstr "非推奨" -#: ../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 "" -"ここで、src レイアウトとフラットレイアウトの動作の違いで重要なものを掲出して" -"おきましょう:" +#: ../source/discussions/setup-py-deprecated.rst:33 +#: ../source/guides/modernize-setup-py-project.rst:30 +msgid "Recommendation" +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 "" -"src レイアウトではそのソースコードを走らせるためにプロジェクトのインストール" -"が要求されますが、フラットレイアウトではそのようなことはありません。" +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python -m pip install .``" +msgstr "``python -m pip install .``" -#: ../source/discussions/src-layout-vs-flat-layout.rst:51 -msgid "" -"This means that the src layout involves an additional step in the " -"development workflow of a project (typically, an :doc:`editable installation " -"` is used for development and a " -"regular installation is used for testing)." -msgstr "" -"これが意味するところは、src レイアウトの場合にはプロジェクトの開発ワークフ" -"ローに追加的なステップ (典型的には、開発には :doc:`編集可能なインストール " -"` を使い、テストには通常のインストール" -"を用いる) が必要になるということです。" +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "``python -m pip install --editable .``" -#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "``python -m build`` [#needs-build]_" + +#: ../source/discussions/setup-py-deprecated.rst:45 msgid "" -"The src layout helps prevent accidental usage of the in-development copy of " -"the code." +"This requires the :ref:`build` dependency. It is recommended to always build " +"and publish both the source distribution and wheel of a project, which is " +"what ``python -m build`` does. If necessary the ``--sdist`` and ``--wheel`` " +"options can be used to generate only one or the other." msgstr "" -"src レイアウトを採用することは、今まさに開発中のソースコードを使ってしまうと" -"いう事故を防ぐことを助けます。" +"これは、:ref:`build` の依存関係を要求します。 ``python -m build`` を実行すれ" +"ばそうなりますが、プロジェクトにおいては常にソースコード配布物とwheelの両方を" +"公開することを推奨します。もし必要であれば、いずれか片方を生成するのに ``--" +"sdist`` や ``--wheel`` のオプションを使うことができます。" -#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +#: ../source/discussions/setup-py-deprecated.rst:52 msgid "" -"This is relevant since the Python interpreter includes the current working " -"directory as the first item on the import path. This means that if an import " -"package exists in the current working directory with the same name as an " -"installed import package, the variant from the current working directory " -"will be used. This can lead to subtle misconfiguration of the project's " -"packaging tooling, which could result in files not being included in a " -"distribution." +"In order to install a setuptools based project, it was common to run :file:" +"`setup.py`'s ``install`` command such as: ``python setup.py install``. " +"Nowadays, the recommended method is to use :ref:`pip` directly with a " +"command like this one: ``python -m pip install .``. Where the dot ``.`` is " +"actually a file system path, it is the path notation for the current " +"directory. Indeed, *pip* accepts a path to a project's source tree directory " +"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 "" -"Python インタープリタはカレントワーキングディレクトリをインポートパスの先頭に" -"含むので、これは妥当なことです。これが意味するところは、もしインストール済み" -"のパッケージと同名のものがカレントワーキングディレクトリに存在するならば、カ" -"レントワーキングディレクトリにあるものが使われるであろうということです。これ" -"によって、配布物に一部ファイル群が含まれない結果に終わるという、プロジェクト" -"のパッケージングツールの微妙な誤設定をもたらしかねません。" +"setuptools ベースのプロジェクトをインストールするためには、``python setup.py " +"install`` のように :file:`setup.py` の ``install`` コマンドを使うことが普通で" +"した。今日では、``python -m pip install .`` のように :ref:`pip` を直接に使う" +"方法が推奨されています。ここでドット ``.`` は、実際にはファイルシステム上のパ" +"スなので、これはカレントディレクトリを示すパス表現です。なんと、 *pip* は " +"``install`` サブコマンドへの引数の形で、ローカルのファイルシステム上のパスを" +"プロジェクトのソースコードツリーを置くべき場所として受け付けるのです。そうい" +"うことですから、これもまた正当なコマンドということになります: ``python -m " +"pip install path/to/project``。" -#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +#: ../source/discussions/setup-py-deprecated.rst:65 msgid "" -"The src layout helps avoid this by keeping import packages in a directory " -"separate from the root directory of the project, ensuring that the installed " -"copy is used." +"As for the installation in *develop* mode aka *editable* mode, instead of " +"``python setup.py develop`` one can use the ``--editable`` option of pip's " +"*install* sub-command: ``python -m pip install --editable .``." msgstr "" -"src レイアウトを使えば、パッケージ群をプロジェクトのルートディレクトリとは異" -"なるディレクトリに置くので、インストール済みのパッケージの方を使用することが" -"保証され、このような誤設定を避ける助けになります。" +"*編集可能 * モードとしても知られる *開発 * モードでのイン" +"ストールのためには、 ``python setup.py develop`` の代わりに pip の *install* " +"サブコマンドの ``--editable`` オプションを使うことができます: ``python -m " +"pip install --editable .``。" -#: ../source/discussions/src-layout-vs-flat-layout.rst:70 +#: ../source/discussions/setup-py-deprecated.rst:70 msgid "" -"The src layout helps enforce that an :doc:`editable installation ` is only able to import files that were meant to " -"be importable." +"One recommended, simple, and straightforward method of building :term:" +"`source distributions ` and :term:" +"`wheels ` is to use the :ref:`build` tool with a command like " +"``python -m build`` which triggers the generation of both distribution " +"formats. If necessary the ``--sdist`` and ``--wheel`` options can be used to " +"generate only one or the other. Note that the build tool needs to be " +"installed separately." msgstr "" -"src レイアウトを使うことで、インポートしようと意図した :doc:`編集可能なインス" -"トール ` だけをインポートするように強" -"制することを助けます。" +":term:`ソースコード配布物 ` および :term:" +"`wheels ` をビルドする方法で推奨されていて単純かつ直截なひとつのやり方" +"は、 :ref:`build` ツールを ``python -m build`` のようなコマンドから使って両方" +"の配布物フォーマットの生成を開始することです。いずれか片方の配布物だけを生成" +"するのであれば、必要に応じて ``--sdist`` や ``--wheel`` のオプションを使うこ" +"とができます。build ツールは個別にインストールする必要があることに注意してく" +"ださい。" -#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +#: ../source/discussions/setup-py-deprecated.rst:80 msgid "" -"This is especially relevant when the editable installation is implemented " -"using a `path configuration file `_ that adds the directory to the import path." +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." msgstr "" -"これは、編集可能なインストール (のパッケージ) がインポートパスにそのディレク" -"トリを追加するように動く `パス設定ファイル `_ を使って実装されている場合に、特に適切です。" +"コマンド ``python setup.py install`` は、setuptools のバージョン *58.3.0* で" +"非推奨になりました。" -#: ../source/discussions/src-layout-vs-flat-layout.rst:78 -msgid "" -"The flat layout would add the other project files (eg: ``README.md``, ``tox." -"ini``) and packaging/tooling configuration files (eg: ``setup.py``, " -"``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/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "他のコマンドについてはどうでしょうか？" -#: ../source/discussions/versioning.rst:6 -#: ../source/specifications/simple-repository-api.rst:310 -msgid "Versioning" -msgstr "バージョニング" +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "他の ``python setup.py`` コマンドを置き換えるものは何でしょうか？" -#: ../source/discussions/versioning.rst:8 -msgid "This discussion covers all aspects of versioning Python packages." -msgstr "" -"この議論では、 Python パッケージのバージョニングについてあらゆる角度からカ" -"バーします。" +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "``python setup.py test``" -#: ../source/discussions/versioning.rst:12 -msgid "Valid version numbers" -msgstr "正当なバージョン番号" +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "推奨されるものは、pytest_ のようなテストランナーを使うことです。" -#: ../source/discussions/versioning.rst:14 +#: ../source/discussions/setup-py-deprecated.rst:99 msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but in order to be compatible with tools " -"like :ref:`pip`, all of them are required to comply with a flexible format " -"for version identifiers, for which the authoritative reference is the :ref:" -"`specification of version specifiers `. Here are some " -"examples of version numbers [#version-examples]_:" +"``python setup.py check``, ``python setup.py register``, and ``python setup." +"py upload``" msgstr "" -"相異なるPythonプロジェクトがそれぞれの事情に合わせて異なるバージョン体系を採" -"用することは構いませんが、しかし、:ref:`pip` のようなツールとの互換性を保つた" -"めには、バージョン識別子のための自由度の高いフォーマット、その権威ある参照先" -"は :ref:`バージョン識別子仕様 ` ですが、これに準拠するこ" -"とが要求されます。ここではバージョン番号のいくつかの例を紹介しましょう " -"[#version-examples]_:" - -#: ../source/discussions/versioning.rst:21 -msgid "A simple version (final release): ``1.2.0``" -msgstr "簡明なバージョン (最終的なリリース): ``1.2.0``" - -#: ../source/discussions/versioning.rst:22 -msgid "A development release: ``1.2.0.dev1``" -msgstr "開発リリース: ``1.2.0.dev1``" +"``python setup.py check``, ``python setup.py register``, および ``python " +"setup.py upload``" -#: ../source/discussions/versioning.rst:23 -msgid "An alpha release: ``1.2.0a1``" -msgstr "アルファリリース: ``1.2.0a1``" +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "信頼されている代替物は :ref:`twine` です:" -#: ../source/discussions/versioning.rst:24 -msgid "A beta release: ``1.2.0b1``" -msgstr "ベータリリース: ``1.2.0b1``" +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" -#: ../source/discussions/versioning.rst:25 -msgid "A release candidate: ``1.2.0rc1``" -msgstr "リリース候補: ``1.2.0rc1``" +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "``python -m twine register dist/*.whl`` [#not-pypi]_" -#: ../source/discussions/versioning.rst:26 -msgid "A post-release: ``1.2.0.post1``" -msgstr "ポストリリース: ``1.2.0.post1``" +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" -#: ../source/discussions/versioning.rst:27 +#: ../source/discussions/setup-py-deprecated.rst:107 msgid "" -"A post-release of an alpha release (possible, but discouraged): ``1.2.0a1." -"post1``" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -"アルファリリースのポストリリース (こういうことも可能ではあるが非推奨): " -"``1.2.0a1.post1``" - -#: ../source/discussions/versioning.rst:28 -msgid "A simple version with only two components: ``23.12``" -msgstr "二つの部分からのみ構成される簡明なバージョン: ``23.12``" - -#: ../source/discussions/versioning.rst:29 -msgid "A simple version with just one component: ``42``" -msgstr "たったひとつの部分から構成される簡明なバージョン: ``42``" +"必ずしもそうではなく、 :term:`PyPI ` でもサポー" +"トされていません。しかし、(例えば :ref:`devpi` のような) 他の :term:`パッケー" +"ジインデックス ` では必要になるかもしれません。" -#: ../source/discussions/versioning.rst:30 -msgid "A version with an epoch: ``1!1.0``" -msgstr "エポック付きのバージョン: ``1!1.0``" +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "``python setup.py --version``" -#: ../source/discussions/versioning.rst:32 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" -"Projects can use a cycle of pre-releases to support testing by their users " -"before a final release. In order, the steps are: alpha releases, beta " -"releases, release candidates, final release. Pip and other modern Python " -"package installers ignore pre-releases by default when deciding which " -"versions of dependencies to install, unless explicitly requested (e.g., with " -"``pip install pkg==1.1a3`` or ``pip install --pre pkg``)." +"A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -"プロジェクトにおいては、最終的なリリースの前にいくつかのプレリリースのサイク" -"ルを置くことで既存ユーザによる試験をサポートすることができます。その段階は、" -"アルファリリース、ベータリリース、リリース候補、最終的なリリースの順です。 " -"pip や他の近代的な Python パッケージインストーラは、依存関係にあるパッケージ" -"のどのバージョンをインストールするかを決定する際、 (例えば ``pip install " -"pkg==1.1a3`` とか ``pip install --pre pkg`` のように) 明示的に要求されていな" -"い限りデフォルト設定ではプレリリース群を無視します。" +"実行可能な代替案は (他にもありますが) setuptools-scm_ に頼ることでしょう:" -#: ../source/discussions/versioning.rst:39 -msgid "" -"The purpose of development releases is to support releases made early during " -"a development cycle, for example, a nightly build, or a build from the " -"latest source in a Linux distribution." -msgstr "" -"開発リリースの目的は、例えば夜毎のビルド のように開発サイクル" -"の早い時期にリリースを行うことや、Linux ディストリビューションの最新のソース" -"コードからビルドを行うことです。" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools_scm``" -#: ../source/discussions/versioning.rst:43 -msgid "" -"Post-releases are used to address minor errors in a final release that do " -"not affect the distributed software, such as correcting an error in the " -"release notes. They should not be used for bug fixes; these should be done " -"with a new final release (e.g., incrementing the third component when using " -"semantic versioning)." -msgstr "" -"ポストリリースは、リリースノート内のエラーのように配布されたソフトウェアに大" -"きな悪影響を与えないようなファイナルリリースの軽微なエラーを修正するために使" -"われます。バグ修正のために使うべきではなく、それは新たな (即ち、セマンティッ" -"クバージョニングを使っているなら第３要素を１だけ増加させた) ファイナルリリー" -"スで行うべきです。" +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "残りのコマンド群" -#: ../source/discussions/versioning.rst:49 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" -"Finally, epochs, a rarely used feature, serve to fix the sorting order when " -"changing the versioning scheme. For example, if a project is using calendar " -"versioning, with versions like 23.12, and switches to semantic versioning, " -"with versions like 1.0, the comparison between 1.0 and 23.12 will go the " -"wrong way. To correct this, the new version numbers should have an explicit " -"epoch, as in \"1!1.0\", in order to be treated as more recent than the old " -"version numbers." -msgstr "" -"最後に、エポックは、稀にしか使われない機能ですが、バージョニングの方法を変更" -"するときに順序を訂正するために使われます。例えば、 23.12 のようなカレンダー" -"バージョニングを使っているプロジェクトが 1.0 のようなセマンティックバージョニ" -"ングに移行するような場合に、 1.0 と 23.12 の間の比較は誤った結果になるでしょ" -"う。これを訂正するために、明示的に示された \"1!1.0\" のようなエポックを持つこ" -"とで、新しいバージョン番号が古いバージョン番号よりもより最近のものとして扱わ" -"れるようにするべきです。" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "このガイド文書では、それらコマンド群の代替案について示唆しません:" -#: ../source/discussions/versioning.rst:59 -msgid "Semantic versioning vs. calendar versioning" -msgstr "セマンティックバージョニング対カレンダーバージョニング" - -#: ../source/discussions/versioning.rst:61 -msgid "" -"A versioning scheme is a formalized way to interpret the segments of a " -"version number, and to decide which should be the next version number for a " -"new release of a package. Two versioning schemes are commonly used for " -"Python packages, semantic versioning and calendar versioning." -msgstr "" -"バージョニング方法とは、バージョン番号の断片を翻訳するために決められたやり方" -"で、パッケージの新しいリリースように次のバージョン番号がどのようなものになる" -"べきかを決めるやり方です。Python パッケージにしばしば用いられる二つのバージョ" -"ニング方法は、セマンティックバージョニングとカレンダーバージョニングです。" - -#: ../source/discussions/versioning.rst:68 -msgid "" -"The decision which version number to choose is up to a project's maintainer. " -"This effectively means that version bumps reflect the maintainer's view. " -"That view may differ from the end-users' perception of what said formalized " -"versioning scheme promises them." -msgstr "" -"どのようなバージョン番号を選択するべきかの決定権はプロジェクトのメンテナに委" -"ねられています。これは、バージョン上げにメンテナの観点を反映しているというこ" -"とを実質的に意味します。そのような観点は、バージョニング方法が約束するやり方" -"についてのエンドユーザの受け取り方とは異なるかも知れません。" - -#: ../source/discussions/versioning.rst:74 -msgid "" -"There are known exceptions for selecting the next version number. The " -"maintainers may consciously choose to break the assumption that the last " -"version segment only contains backwards-compatible changes. One such case is " -"when security vulnerability needs to be addressed. Security releases often " -"come in patch versions but contain breaking changes inevitably." -msgstr "" -"次のバージョン番号を選定する上で既知の例外があります。保守者は、最後のバー" -"ジョン断片が後方互換性を保つための変更だけを含むという想定を破るような選択を" -"意識的に行っても構いません。そのような場合の一つは、セキュリティ上の脆弱性を" -"修正する必要がある時です。セキュリティリリースは、しばしば、パッチバージョン" -"として提供されますが、そうすると必然的にここで述べているような変更をもたらし" -"ます。" - -#: ../source/discussions/versioning.rst:84 -#: ../source/specifications/version-specifiers.rst:721 -msgid "Semantic versioning" -msgstr "セマンティックバージョニング" - -#: ../source/discussions/versioning.rst:86 -msgid "" -"The idea of *semantic versioning* (or SemVer) is to use 3-part version " -"numbers, *major.minor.patch*, where the project author increments:" -msgstr "" -"*セマンティックバージョニング* (または SemVer) のアイデアは、３個の部分から構" -"成されるバージョン番号、つまり *major.minor.patch* を用いることで、プロジェク" -"トの作者は以下のように各段階の数字を増やします:" - -#: ../source/discussions/versioning.rst:89 -msgid "*major* when they make incompatible API changes," -msgstr "APIの変更で互換性を失う時には *major* 番号、" - -#: ../source/discussions/versioning.rst:90 -msgid "" -"*minor* when they add functionality in a backwards-compatible manner, and" -msgstr "後方互換性を保ったままで新機能を追加する場合には *minor* を、そして" - -#: ../source/discussions/versioning.rst:91 -msgid "*patch*, when they make backwards-compatible bug fixes." -msgstr "後方互換性を維持したままのバグ修正の場合には *patch* を増加させます。" - -#: ../source/discussions/versioning.rst:93 -msgid "" -"A majority of Python projects use a scheme that resembles semantic " -"versioning. However, most projects, especially larger ones, do not strictly " -"adhere to semantic versioning, since many changes are technically breaking " -"changes but affect only a small fraction of users. Such projects tend to " -"increment the major number when the incompatibility is high, or to signal a " -"shift in the project, rather than for any tiny incompatibility [#semver-" -"strictness]_. Conversely, a bump of the major version number is sometimes " -"used to signal significant but backwards-compatible new features." -msgstr "" -"Python プロジェクトの大多数は、セマンティックバージョニングに似た方式を使って" -"います。しかしながら、ほとんどのプロジェクト、とりわけ大規模なものでは、多く" -"の変更が技術的には互換性を保たないけれども少数のユーザにしか影響を与えないの" -"で、セマンティックバージョニングに厳密に従うことはしていません。そのようなプ" -"ロジェクトでは、小さな非互換性であってもいつも major 番号を増やす [#semver-" -"strictness]_ というよりは、非互換性が高い場合やプロジェクトの方向性が変わるこ" -"とを示す時に増やす傾向にあります。逆に、時には、重要ではあるが後方互換性を損" -"なわない新機能に注目を集めるために major バージョン番号を増加させることもあり" -"ます。" - -#: ../source/discussions/versioning.rst:103 -msgid "" -"For those projects that do use strict semantic versioning, this approach " -"allows users to make use of :ref:`compatible release version specifiers " -"`, with the ``~=`` operator. For " -"example, ``name ~= X.Y`` is roughly equivalent to ``name >= X.Y, == X.*``, i." -"e., it requires at least release X.Y, and allows any later release with " -"greater Y as long as X is the same. Likewise, ``name ~= X.Y.Z`` is roughly " -"equivalent to ``name >= X.Y.Z, == X.Y.*``, i.e., it requires at least X.Y.Z " -"and allows a later release with same X and Y but higher Z." -msgstr "" -"厳密なセマンティックバージョニングを採用しているプロジェクトでは、このアプ" -"ローチによってユーザが ``~=`` 演算子を用いた :ref:`互換リリースバージョン指定" -"子 ` を使うことができるようになりま" -"す。例えば、 ``name ~= X.Y`` は ``name >= X.Y, == X.*`` と大まかに言って等価" -"で、つまり、少なくともリリース X.Y を要求していて X が同じである限りは Y が大" -"きくなった後続リリースを許容するということです。同様に、 ``name ~= X.Y.Z`` は" -"大まかに ``name >= X.Y.Z, == X.Y.*`` と等価で、少なくとも X.Y.Z を要求してい" -"て X と Y が同じである限り Z が大きくなった後続のリリースを許容するということ" -"です。" - -#: ../source/discussions/versioning.rst:112 -msgid "" -"Python projects adopting semantic versioning should abide by clauses 1-8 of " -"the `Semantic Versioning 2.0.0 specification `_." -msgstr "" -"セマンティックバージョニングを採用しているPythonプロジェクトでは、 `セマン" -"ティックバージョニング 2.0.0 仕様書 `_ の第１節から第８節までを甘受" -"すべきです。" - -#: ../source/discussions/versioning.rst:115 -msgid "" -"The popular :doc:`Sphinx ` documentation generator is an " -"example project that uses strict semantic versioning (:doc:`Sphinx " -"versioning policy `). The famous :doc:" -"`NumPy ` scientific computing package explicitly uses \"loose\" " -"semantic versioning, where releases incrementing the minor version can " -"contain backwards-incompatible API changes (:doc:`NumPy versioning policy " -"`)." -msgstr "" -"人気のあるドキュメンテーションジェネレータである :doc:`Sphinx ` は、厳密なセマンティックバージョニング (:doc:`Sphinx バージョニング方" -"針 `) を採用しているプロジェクトの例です。" -"有名な科学計算パッケージである :doc:`NumPy ` は、マイナーバー" -"ジョンの更新でも後方互換性のない API 変更を含む場合がある (:doc:`NumPy バー" -"ジョニング方針 `) ということで、明示的に \"ゆる" -"い\" セマンティックバージョニングを採用しています。" - -#: ../source/discussions/versioning.rst:124 -msgid "Calendar versioning" -msgstr "カレンダーバージョニング" - -#: ../source/discussions/versioning.rst:126 -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 "" -"セマンティックバージョニングはすべてのプロジェクト向きと言うわけではなく、例" -"えば定期的なリリースサイクルに従う場合や、ある機能を削除する前に何世代にもわ" -"たるリリースで非推奨(deprecation)の警告を出すような場合には適していないかもし" -"れません。" - -#: ../source/discussions/versioning.rst:130 -msgid "" -"A key advantage of date-based versioning, or `calendar versioning " -"`_ (CalVer), is that it is straightforward to tell how old the base " -"feature set of a particular release is given just the version number." -msgstr "" -"`カレンダーバージョニング `_ (CalVer) の最大の利点は、バージョン番号" -"を見ただけで基盤になっている機能セットがどれほど古いのかが直截にわかることで" -"す。" - -#: ../source/discussions/versioning.rst:134 -msgid "" -"Calendar version numbers typically take the form *year.month* (for example, " -"23.12 for December 2023)." -msgstr "" -"カレンダーバージョン番号は、典型的には *年.月* (例えば2023年12月に対して " -"23.12) の形を取ります。" - -#: ../source/discussions/versioning.rst:137 -msgid "" -":doc:`Pip `, the standard Python package installer, uses calendar " -"versioning." -msgstr "" -"標準的な Python パッケージインストーラである :doc:`Pip ` はカレン" -"ダーバージョニングを採用しています。" - -#: ../source/discussions/versioning.rst:142 -msgid "Other schemes" -msgstr "他の方法" - -#: ../source/discussions/versioning.rst:144 -msgid "" -"Serial versioning refers to the simplest possible versioning scheme, which " -"consists of a single number incremented every release. 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/discussions/versioning.rst:150 -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.month* 型のバー" -"ジョン番号付与方式を作り出して、バージョン番号がリリース年を示すけれどもその" -"年の中のどのリリースサイクルかを特定することについてはあまり気にしていないと" -"いうプロジェクトもあるでしょう。" - -#: ../source/discussions/versioning.rst:158 -#: ../source/specifications/version-specifiers.rst:114 -msgid "Local version identifiers" -msgstr "ローカルのバージョン指定子" - -#: ../source/discussions/versioning.rst:160 -msgid "" -"Public version identifiers are designed to support distribution via :term:" -"`PyPI `. Python packaging tools also support " -"the notion of a :ref:`local version identifier `, " -"which can be used to identify local development builds not intended for " -"publication, or modified variants of a release maintained by a redistributor." -msgstr "" -"公的バージョン識別子は、 :term:`PyPI ` を通じた" -"配布をサポートするように設計されています。Pythonのパッケージングツール群は、" -"ローカルでの開発でビルドごとの識別子や再配布者が維持管理している変種のリリー" -"スの識別子として用いるような :ref:`局所的バージョン識別子 ` の考え方もサポートします。" - -#: ../source/discussions/versioning.rst:166 -msgid "" -"A local version identifier takes the form of a public version identifier, " -"followed by \"+\" and a local version label. For example, a package with " -"Fedora-specific patches applied could have the version \"1.2.1+fedora.4\". " -"Another example is versions computed by setuptools-scm_, a setuptools plugin " -"that reads the version from Git data. In a Git repository with some commits " -"since the latest release, setuptools-scm generates a version like \"0.5." -"dev1+gd00980f\", or if the repository has untracked changes, like \"0.5." -"dev1+gd00980f.d20231217\"." -msgstr "" -"ローカルバージョン識別子は、公的バージョン識別子の後ろに \"+\" とローカルバー" -"ジョンラベルを並べた形を採ります。例えば、Fedora に特有のパッチが適用された" -"パッケージは、 \"1.2.1+fedora.4\" といったバージョンになるという具合です。別" -"の例としては、 setuptools-scm_ によって計算されたバージョンで、Git のデータか" -"らバージョンを読み取る setuptools プラグインによるものです。最新のリリース以" -"後に幾つかのコミットがなされた Git リポジトリでは setuptools-scm は \"0.5." -"dev1+gd00980f\" のようなバージョンを生成することもありますし、トラックされて" -"いない変更のあるリポジトリなら \"0.5.dev1+00980f.d20231217\" のようになること" -"があります。" - -#: ../source/discussions/versioning.rst:178 -msgid "" -"Some more examples of unusual version numbers are given in a `blog post " -"`_ by Seth Larson." -msgstr "" -"普通でないバージョン番号のいくつかの例が Seth Larson によって `ブログポスト " -"`_ に挙げられています。" - -#: ../source/discussions/versioning.rst:181 -msgid "" -"For some personal viewpoints on this issue, see these blog posts: `by Hynek " -"Schlawak `_, `by Donald Stufft `_, `by Bernát Gábor `_, `by Brett Cannon " -"`_. For a humoristic take, read about ZeroVer_." -msgstr "" -"この問題に関する個人的な観点については、次のようなブログポストを見てくださ" -"い: `Hynek Schlawak によるもの `_ ・ `Donald Stufft " -"によるもの `_ ・ `Bernát Gábor によるもの `_ ・ `Brett Cannon によるもの `_ 。ユー" -"モラスなものが良ければ、 ZeroVer_ について読んでみてください。" - -#: ../source/discussions/wheel-vs-egg.rst:5 -msgid "Wheel vs Egg" -msgstr "Wheel対Egg" - -#: ../source/discussions/wheel-vs-egg.rst:7 -msgid "" -":term:`Wheel` and :term:`Egg` are both packaging formats that aim to support " -"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 "" -":term:`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`のフォーマットは、2004年に:ref:`setuptools`によって、また、:term:" -"`Wheel`のフォーマットは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`は、現在、Pythonにおける :term:`ビルド済配布物 `および :term:`バイナリ配布物 `の標準である" -"とみなされています。" - -#: ../source/discussions/wheel-vs-egg.rst:17 -msgid "" -"Here's a breakdown of the important differences between :term:`Wheel` and :" -"term:`Egg`." -msgstr ":term:`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`には対応するPEPがありません。" - -#: ../source/discussions/wheel-vs-egg.rst:24 -msgid "" -":term:`Wheel` is a :term:`distribution ` format, i.e a " -"packaging format. [1]_ :term:`Egg` was both a distribution format and a " -"runtime installation format (if left zipped), and was designed to be " -"importable." -msgstr "" -":term:`Wheel`は :term:`配布物 `のフォーマット、つまり、" -"パッケージのフォーマットです。[1]_ :term:`Egg`は配布物のフォーマットでもあ" -"り、かつ、(もし圧縮されたままであれば)実行時のインストールフォーマットであっ" -"てimportができるように設計されています。" - -#: ../source/discussions/wheel-vs-egg.rst:28 -msgid "" -":term:`Wheel` archives do not include .pyc files. Therefore, when the " -"distribution only contains Python files (i.e. no compiled extensions), and " -"is compatible with Python 2 and 3, it's possible for a wheel to be " -"\"universal\", similar to an :term:`sdist `." -msgstr "" -":term:`Wheel`形式のファイルには.pycファイルが含まれていません。従って、配布物" -"には(コンパイル済のファイル抜きの)Pythonファイルのみ(含み、Pythonのバージョン" -"2と3で使用可能ですので、 :term:`sdist `と" -"同様にwheelは「汎用」であると言うことができます。" - -#: ../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-compliant <376>`に従って ``.dist-info`` ディレク" -"トリを用います。Eggは ``.egg-info`` を用います。" - -#: ../source/discussions/wheel-vs-egg.rst:36 -msgid "" -":term:`Wheel` has a :pep:`richer file naming convention <425>`. A single " -"wheel archive can indicate its compatibility with a number of Python " -"language versions and implementations, ABIs, and system architectures." -msgstr "" -":term:`Wheel`には:pep:`richer file naming convention <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 "" -":term:`Wheel` is internally organized by `sysconfig path type `_, therefore making " -"it easier to convert to other formats." -msgstr "" -":term:`Wheel`は内部では`sysconfigパスの型 `_で整理されているので、他のフォーマットに" -"変換するのがより簡単になっています。" - -#: ../source/discussions/wheel-vs-egg.rst:47 -msgid "" -":term:`Egg` uploads have been disabled for upload to PyPI, per :pep:`715`. " -"Read the `deprecation notice `_ for more information." -msgstr "" -":term:`Egg` によるアップロードは、 :pep:`715` に従って PyPI へのアップロード" -"としては無効になっています。もっと情報が欲しい場合は、 `非推奨のお知らせ " -" `_ を読んでください。" - -#: ../source/discussions/wheel-vs-egg.rst:53 -#: ../source/discussions/package-formats.rst:184 -msgid "" -"Circumstantially, in some cases, wheels can be used as an importable runtime " -"format, although :ref:`this is not officially supported at this time `." -msgstr "" -"状況としては、 :ref:`現時点で公式にはサポートされていません ` が、 一部のケースで wheel ファイルをイン" -"ポート可能な稼働時(runtime)フォーマットとして使うことが可能です。" - -#: ../source/flow.rst:3 -msgid "The Packaging Flow" -msgstr "パッケージングの流れ" - -#: ../source/flow.rst:5 -msgid "" -"The document aims to outline the flow involved in publishing/distributing a :" -"term:`distribution package `, usually to the `Python " -"Package Index (PyPI)`_. It is written for package publishers, who are " -"assumed to be the package author." -msgstr "" -"文書は、大抵は `Python パッケージインデックス (PyPI) `_ への :term:`配布パッケージ ` の公開や配布に必" -"要な作業の流れをおおまかに描き出すことを目的としています。パッケージの作者と" -"目される、パッケージを公開する人向けに書かれました。" - -#: ../source/flow.rst:12 -msgid "" -"While the :doc:`tutorial ` walks through the " -"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 "" -"Prepare a configuration file describing the package metadata (name, version " -"and so forth) and how to create the build artifacts. For most packages, this " -"will be a :file:`pyproject.toml` file, maintained manually in the source " -"tree." -msgstr "" -"パッケージのメタデータ (名前・バージョン・その他) とビルド成果物を作成するた" -"めの方法を記述した設定ファイルを用意してください。ほとんどのパッケージ向けに" -"は、これは、ソースツリー内で手動で維持管理される :file:`pyproject.toml` ファ" -"イルを準備するということになるでしょう。" - -#: ../source/flow.rst:27 -msgid "" -"Create build artifacts to be sent to the package distribution service " -"(usually PyPI); these will normally be a :term:`source distribution " -"(\"sdist\") ` and one or more :term:" -"`built distributions (\"wheels\") `. These are made by a " -"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 パッケージの場合には、共通の wheel がひとつだけ存在するということもし" -"ばしばあります。" - -#: ../source/flow.rst:35 -msgid "Upload the build artifacts to the package distribution service." -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 "" -"Install it in their Python environment, usually in its ``site-packages`` " -"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 "" -"これら最後のふたつのステップは、典型的な場合には、エンドユーザが ``pip " -"install`` を走らせた時に :ref:`pip` によって実行されます。" - -#: ../source/flow.rst:50 -msgid "The steps above are described in more detail below." -msgstr "上記のステップについては、以下にもっと詳しく記述してあります。" - -#: ../source/flow.rst:53 -msgid "The source tree" -msgstr "ソースコードツリー" - -#: ../source/flow.rst:55 -msgid "" -"The source tree contains the package source code, usually a checkout from a " -"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" -msgstr "設定ファイル" - -#: ../source/flow.rst:62 -msgid "" -"The configuration file depends on the tool used to create the build " -"artifacts. The standard practice is to use a :file:`pyproject.toml` file in " -"the `TOML format`_." -msgstr "" -"ビルド成果物を作成するのに用いるツールによって設定ファイルは変わります。" -"`TOML フォーマット `_ で書かれた `pyproject.toml` ファイルを使う" -"のが標準的な慣習です。" - -#: ../source/flow.rst:68 -msgid "" -"At a minimum, the :file:`pyproject.toml` file needs a ``[build-system]`` " -"table specifying your build tool. There are many build tools available, " -"including but not limited to :ref:`flit`, :ref:`hatch`, :ref:`pdm`, :ref:" -"`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` ・ `trample`_ ・ `whey`_ を含めて他にもさまざまなものがあり" -"ます。それぞれのツールの説明文書には、 ``[build-system]`` に何を書けば良いか" -"が示されていることでしょう。" - -#: ../source/flow.rst:77 -msgid "For example, here is a table for using :ref:`hatch`:" -msgstr "例えば、 :ref:`hatch` を使う場合のテーブルは次のようになります:" - -#: ../source/flow.rst:85 -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 " -"\":term:`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." -msgstr "" -":file:`pyproject.toml` ファイルの中のそのようなテーブルを用いることで、 :ref:" -"`build` のような \":term:`フロントエンド `\" のツールが、ビル" -"ド成果物を作成するためにあなたが選んだビルドツールの \":term:`バックエンド " -"`\" を実行することができます。あなたが選んだビルドツールが独自" -"のフロントエンドを提供しても構いません。 :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)," -msgstr "" -":doc:`コアとなるメタデータ ` (名前・バージョ" -"ン・作者・その他) を含む ``[project]``、" - -#: ../source/flow.rst:101 -msgid "a ``[tool]`` table containing tool-specific configuration options." -msgstr "ツール特有の設定オプションを含んだ ``[tool]`` テーブル。" - -#: ../source/flow.rst:103 -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:108 -msgid "Build artifacts" -msgstr "ビルド成果物" - -#: ../source/flow.rst:111 -msgid "The source distribution (sdist)" -msgstr "" -"`ソースコード配布物 (またはsdist) `" - -#: ../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 " -"may also include tests and documentation. These are useful for end users " -"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: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:126 -msgid "" -"Or, your build tool may provide its own interface for creating an sdist." -msgstr "" -"あるいは、あなたの選んだツールが、 sdist を生成するためのツール独自のインタ" -"フェースを提供しているかもしれません。" - -#: ../source/flow.rst:130 -msgid "The built distributions (wheels)" -msgstr "ビルド済み配布物 (wheels)" - -#: ../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 ファイルの内容" -"を ``site-packages`` ディレクトリに単純に展開することができます。これによって" -"インストールが素早く行われ、エンドユーザにとってより便利であると言えるでしょ" -"う。" - -#: ../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 " -"of Python interpreter, operating system, and CPU architecture that it " -"supports. If a suitable wheel file is not available, tools like :ref:`pip` " -"will fall back to installing the source distribution." -msgstr "" -"純 Python パッケージでは、典型的には、ひとつの \"万能型\" の wheel さえあれば" -"十分です。コンパイル済みのバイナリ拡張を伴うパッケージでは、そのパッケージが" -"サポートする Python インタプリタ・オペレーティングシステム・ CPU アーキテク" -"チャの組み合わせのそれぞれについて wheel ファイルが必要になります。適切な " -"wheel ファイルが利用できない場合には、 :ref:`pip` のようなツールはソースコー" -"ド配布物からのインストールにフォールバックします。" - -#: ../source/flow.rst:150 -msgid "Or, your build tool may provide its own interface for creating a wheel." -msgstr "" -"あるいは、あなたの選んだビルドツールが wheel を生成するための独自のインタ" -"フェースを提供しているかもしれません。" - -#: ../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 と wheel の両方を作成することです; 上記の例は意図的に特定の動作をさ" -"せています。" - -#: ../source/flow.rst:159 -msgid "Upload to the package distribution service" -msgstr "パッケージ配布サービスへアップロードする" - -#: ../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:168 -msgid "Or, your build tool may provide its own interface for uploading." -msgstr "" -"あるいは、あなたの選んだビルドツールにアップロードのための独自のインタフェー" -"スが備わっているかもしれません。" - -#: ../source/flow.rst:171 -msgid "Download and install" -msgstr "ダウンロードとインストール" - -#: ../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:181 -msgid "" -"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" -"ref:`pdm`." -msgstr "" -"エンドユーザは、 :ref:`pipenv` ・ :ref:`poetry` ・ :ref:`ppm` のような他の" -"ツールを使うことも可能です。" - -#: ../source/glossary.rst:3 -msgid "Glossary" -msgstr "用語集" - -#: ../source/glossary.rst:8 -msgid "Binary Distribution" -msgstr "バイナリ配布物" - -#: ../source/glossary.rst:11 -msgid "" -"A specific kind of :term:`Built Distribution` that contains compiled " -"extensions." -msgstr "" -"`ビルド済配布物 `の特定の種類で、コンパイル済みの拡張部分" -"を含むもの。" - -#: ../source/glossary.rst:14 -msgid "Build Backend" -msgstr "ビルドバックエンド" - -#: ../source/glossary.rst:17 -msgid "" -"A library that takes a source tree or :term:`source distribution ` and builds a source distribution or :term:" -"`wheel ` from it. The build is delegated to the backend by a :term:" -"`frontend `. All backends offer a standardized interface." -msgstr "" -"ソースコードツリーや :term:`ソースコード配布物 ` を受け取って、そこからソースコード配布物や :term:`wheel " -"` をビルドするライブラリ。ビルド自体は :term:`フロントエンド ` によってバックエンドに任されます。すべてのバックエンドは標準化され" -"たインターフェースを提供します。" - -#: ../source/glossary.rst:24 -msgid "" -"Examples of build backends are :ref:`flit's flit-core `, :ref:`hatch's " -"hatchling `, :ref:`maturin`, :ref:`meson-python`, :ref:`scikit-build-" -"core`, and :ref:`setuptools`." -msgstr "" -"ビルドバックエンドの例としては、 :ref:`flit の flit-core ` 、 :ref:" -"`hatchのhatchling ` 、 :ref:`maturin` 、 :ref:`meson-python` 、 :ref:" -"`scikit-build-core` 、 :ref:`setuptools` があります。" - -#: ../source/glossary.rst:32 -msgid "Build Frontend" -msgstr "ビルドフロントエンド" - -#: ../source/glossary.rst:35 -msgid "" -"A tool that users might run that takes arbitrary source trees or :term:" -"`source distributions ` and builds " -"source distributions or :term:`wheels ` from them. The actual " -"building is delegated to each source tree's :term:`build backend `." -msgstr "" -"任意のソースコードツリーまたは :term:`ソースコード配布物 ` を入力として、それらからソースコード配布物また" -"は :term:`wheels ` をビルドするためにユーザが走らせるであろうツール。" -"実際のビルド作業は、それぞれのソースコードツリーの :term:`ビルドバックエンド " -"` に委任されます。" - -#: ../source/glossary.rst:42 -msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." -msgstr "" -"ビルドフロントエンドの例としては、 :ref:`pip` や :ref:`build` があります。" - -#: ../source/glossary.rst:44 -msgid "Built Distribution" -msgstr "ビルド済配布物" - -#: ../source/glossary.rst:47 -msgid "" -"A :term:`Distribution ` format containing files and " -"metadata that only need to be moved to the correct location on the target " -"system, to be installed. :term:`Wheel` is such a format, whereas distutil's :" -"term:`Source Distribution ` is not, in " -"that it requires a build step before it can be installed. This format does " -"not imply that Python files have to be precompiled (:term:`Wheel` " -"intentionally does not include compiled Python files)." -msgstr "" -":term:`配布物 `とは、ターゲットとなるシステムの適切な位" -"置に移動することでインストールされるファイルやメタデータを内包したフォーマッ" -"トです。:term:`Wheel`はそのようなフォーマットですが、他方で、distutilの :" -"term:`ソースコード配布物 `, :term:`modules `, and other resource files that are used " -"to distribute a :term:`Release`. The archive file is what an end-user will " -"download from the internet and install." -msgstr "" -":term:`モジュール `すなわちPythonの :term:`パッケージ `や、ある :term:`Release`を配布するために使われるその他のリソースファ" -"イルを内部に含むバージョン付きアーカイブファイル。アーカイブファイルはエンド" -"ユーザがインターネットからダウンロードしてインストールするものです。" - -#: ../source/glossary.rst:64 -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\". See :ref:`distribution-package-vs-import-package` for a " -"breakdown of the differences." -msgstr "" -"配布パッケージは単語ひとつで「パッケージ」や「配布物」と呼ばれることもしばし" -"ばですが、本ガイドでは、 :term:`インポートパッケージ `(これも" -"通常は単に「パッケージ」と呼ばれます)や他の種類の配布物(例えばLinuxディストリ" -"ビューションやPython言語の配布物)でよく単語ひとつの「配布物」と呼ばれるものと" -"の混同を避けるために明確に述べる必要がある場合には、長い方の用語を用いること" -"があります。" - -#: ../source/glossary.rst:72 -msgid "Egg" -msgstr "卵" - -#: ../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:`ビルド済配布物 `フォーマットは :ref:`setuptools`に" -"よって導入されましたが、 :term:`Wheel`によって置き換えられつつあります。詳細" -"については、 :doc:`Python Eggsの内部構造 ` や `Python Eggs `_ を参照してください。" - -#: ../source/glossary.rst:79 ../source/glossary.rst:78 -msgid "Extension Module" -msgstr "拡張モジュール" - -#: ../source/glossary.rst:82 ../source/glossary.rst:81 -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 " -"single dynamically loadable pre-compiled file, e.g. a shared object (.so) " -"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 "" -":term:`モジュール `とは、Pythonの実装のうちの低レベル言語で書かれた部" -"分で、C/C++で書かれたCythonやJavaで書かれたJythonが該当する。典型的には動的に" -"ロードできるコンパイル済みのファイルをひとつ含んでいて、Unix上では共有オブ" -"ジェクトファイル(.so)、Windows上ではDLL(拡張子.pydを与えられる)のPython拡張、" -"Jython拡張ではJavaのクラスファイルの形を取る。" - -#: ../source/glossary.rst:89 ../source/glossary.rst:88 -msgid "Known Good Set (KGS)" -msgstr "既知の良好なセット" - -#: ../source/glossary.rst:92 ../source/glossary.rst:91 -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 " -"specific set of packages is declared a known good set. This term is commonly " -"used by frameworks and toolkits which are comprised of multiple individual " -"distributions." -msgstr "" -"(KGSとは)相互に互換性のある特定のバージョンの配布物の集合。典型的には、テスト" -"スイートで全てのテストに合格して実行できるようなパッケージの特定の組み合わせ" -"が既知の良好なセット(KGS)であると宣言されます。この用語は、個々の配布物を複数" -"組み合わせて構成されるフレームワークやツールキットで共通して用いられます。" - -#: ../source/glossary.rst:98 ../source/glossary.rst:97 -msgid "Import Package" -msgstr "インポートパッケージ" - -#: ../source/glossary.rst:101 ../source/glossary.rst:100 -msgid "" -"A Python module which can contain other modules or recursively, other " -"packages." -msgstr "" -"直接に、あるいは何段階になっても良いが、他のパッケージを組み込んで使うような" -"Pythonモジュール。" - -#: ../source/glossary.rst:104 ../source/glossary.rst:103 -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\". See :ref:`distribution-package-vs-import-" -"package` for a breakdown of the differences." -msgstr "" -"インポートパッケージは、より普通には「パッケージ」という１単語の用語で呼ばれ" -"ますが、本ガイドでは、同様に単に「パッケージ」と呼ばれることが普通である :" -"term:`配布物パッケージ `との混同を避けるために必要な場" -"合には、長い方の用語を用いることにします。" - -#: ../source/glossary.rst:109 ../source/glossary.rst:108 -msgid "Module" -msgstr "モジュール" - -#: ../source/glossary.rst:112 ../source/glossary.rst:111 -msgid "" -"The basic unit of code reusability in Python, existing in one of two types: :" -"term:`Pure Module`, or :term:`Extension Module`." -msgstr "" -"Pythonにおけるソースコード再利用の基本的な単位で、 :term:`Pure Module`か :" -"term:`Extension Module`の二つのタイプのうちのいずれか。" - -#: ../source/glossary.rst:115 ../source/glossary.rst:114 -msgid "Package Index" -msgstr "パッケージインデックス" - -#: ../source/glossary.rst:118 ../source/glossary.rst:117 -msgid "" -"A repository of distributions with a web interface to automate :term:" -"`package ` discovery and consumption." -msgstr "" -":term:`パッケージ `の発見・消費(訳註、意訳になるが検" -"索・ダウンロードが適切か)を自動化するwebインターフェイスを伴った配布物のリポ" -"ジトリ。" - -#: ../source/glossary.rst:121 ../source/glossary.rst:120 -msgid "Per Project Index" -msgstr "プロジェクト単位の索引" - -#: ../source/glossary.rst:124 ../source/glossary.rst:123 -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 "" -"ある :term:`プロジェクト `が嗜好するか要求する依存関係を解決するため" -"に、:term:`プロジェクト `の単位で示された仲間内または非公式の :term:" -"`パッケージ索引 `。" - -#: ../source/glossary.rst:128 ../source/guides/hosting-your-own-index.rst:62 -#: ../source/guides/index-mirrors-and-caches.rst:52 ../source/glossary.rst:127 -msgid "Project" -msgstr "プロジェクト" - -#: ../source/glossary.rst:131 ../source/glossary.rst:130 -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:`配" -"布物 `として意図的にパッケージされたもの。" - -#: ../source/glossary.rst:135 ../source/glossary.rst:134 -msgid "" -"Since most projects create :term:`Distributions ` " -"using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" -"`setuptools`, another practical way to define projects currently is " -"something that contains a :term:`pyproject.toml`, :term:`setup.py`, or :term:" -"`setup.cfg` file at the root of the project source directory." -msgstr "" -"ほとんどのプロジェクトで :pep:`518` ``build-system``として :ref:`distutils`" -"か :ref:`setuptools`を用いて :term:`配布物 `を作成しま" -"すので、現時点でプロジェクトを定義するもうひとつの実践的な方法は、プロジェク" -"トのソースコードの一番上のディレクトリに :term:`pyproject.toml`や :term:" -"`setup.py`または :term:`setup.cfg`のファイルを含む何ものかというものです。" - -#: ../source/glossary.rst:141 ../source/glossary.rst:140 -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:`リリース `を含んでいて、各リリースは" -"ひとつまたはより多くの :term:`配布物 `を内包していま" -"す。" - -#: ../source/glossary.rst:146 ../source/glossary.rst:145 -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 "" -"そのプロジェクトを稼働させるためにインポートされるパッケージの名前に因んでプ" -"ロジェクトに名前をつけるのが普通であるという強い慣習があることを覚えておいて" -"ください。しかしながら、常にそうしなければならないわけではありません。「なん" -"とか」というプロジェクトから配布物をインストールしていながらも、「かんとか」" -"(訳註、「なんとか」とは無関係の別の名前の例)という名前でのみインポート可能な" -"パッケージを提供することは可能です。" - -#: ../source/glossary.rst:152 ../source/glossary.rst:151 -msgid "Pure Module" -msgstr "純粋なモジュール" - -#: ../source/glossary.rst:155 ../source/glossary.rst:154 -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``ファイル)に収められた :term:`モジュール `。" - -#: ../source/glossary.rst:158 ../source/glossary.rst:157 -msgid "Python Packaging Authority (PyPA)" -msgstr "Pythonパッケージングオーソリティ(PyPA)" - -#: ../source/glossary.rst:161 ../source/glossary.rst:160 -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 " -"projects on `GitHub `_ and `Bitbucket `_, and discuss issues on the `distutils-sig mailing list " -"`_ and " -"`the Python Discourse forum `__." -msgstr "" -"PyPAは、Pythonのパッケージングに関係する多くのプロジェクトを維持管理する作業" -"グループです。その活動の一環として :doc:`papa.io ` を維持管理して" -"おり、 `GitHub `_ と `Bitbucket `_ に関連プロジェクトを置くとともに、 `distutils-sig メーリングリス" -"ト `_ と " -"`Python談話フォーラム `__ で議論を進" -"めています。" - -#: ../source/glossary.rst:170 ../source/glossary.rst:169 -msgid "Python Package Index (PyPI)" -msgstr "Pythonパッケージインデックス (PyPI)" - -#: ../source/glossary.rst:173 ../source/glossary.rst:172 -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 `_ は、Pythonコミュニティにとってデフォルトの :term:" -"`Package Index`です。ここから配布物を取り出し、また、配布するためにすべての" -"Python開発者に開かれています。" - -#: ../source/glossary.rst:176 ../source/glossary.rst:175 -msgid "pypi.org" -msgstr "pypi.org" - -#: ../source/glossary.rst:179 ../source/glossary.rst:178 -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 パッケージインデックス" -"(PyPI)` のためのドメイン名です。2017年にそれまでのドメイン名である ``pypi." -"python.org`` を置き換えました。 :ref:`warehouse`を使っています。" - -#: ../source/glossary.rst:183 ../source/glossary.rst:182 -msgid "pyproject.toml" -msgstr "pyproject.toml" - -#: ../source/glossary.rst:186 ../source/glossary.rst:185 -msgid "" -"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." -msgstr "" -"ツール不可知論者の :term:`プロジェクト ` 仕様を示すファイル。 :pep:" -"`518` で定義。" - -#: ../source/glossary.rst:188 ../source/glossary.rst:187 -msgid "Release" -msgstr "リリース" - -#: ../source/glossary.rst:191 ../source/glossary.rst:190 -msgid "" -"A snapshot of a :term:`Project` at a particular point in time, denoted by a " -"version identifier." -msgstr "" -"ある特定の時点における :term:`プロジェクト `のスナップショットで、" -"バージョン識別子付きのもの。" - -#: ../source/glossary.rst:194 ../source/glossary.rst:193 -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:`配布物 ` を公開" -"することを伴います。例えば、あるプロジェクトのバージョン1.0がリリースされたな" -"らば、ソースコード配布物とWindowsインストーラ付配布物の両方が利用可能となって" -"いるという具合です。" - -#: ../source/glossary.rst:199 ../source/glossary.rst:198 -msgid "Requirement" -msgstr "要求事項" - -#: ../source/glossary.rst:202 ../source/glossary.rst:201 -msgid "" -"A specification for a :term:`package ` to be " -"installed. :ref:`pip`, the :term:`PYPA ` " -"recommended installer, allows various forms of specification that can all be " -"considered a \"requirement\". For more information, see the :ref:`pip:pip " -"install` reference." -msgstr "" -"インストールされる :term:`パッケージ ` の仕様。 :term:" -"`PYPA ` が推奨するインストーラである :ref:" -"`pip` では、「要求事項」とも解釈できる仕様を様々な様式で書くことを許容してい" -"ます。詳細については、 :ref:`pip:pip install` の項を参照してください。" - -#: ../source/glossary.rst:208 ../source/glossary.rst:207 -msgid "Requirement Specifier" -msgstr "要求事項識別子" - -#: ../source/glossary.rst:211 ../source/glossary.rst:210 -msgid "" -"A format used by :ref:`pip` to install packages from a :term:`Package " -"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:`パッケージインデックス `からパッケージをインストールす" -"るために :ref:`pip` で用いられる様式。この様式の EBNF 文法構造については、 :" -"ref:`依存関係指定子 ` を見てください。例えば、 " -"\"foo>=1.3\" は要求事項識別子であり、 \"foo\" の部分がプロジェクトの名称で、 " -"\">=1.3\" の部分は :term:`バージョン指定子 ` です" - -#: ../source/glossary.rst:216 ../source/glossary.rst:215 -msgid "Requirements File" -msgstr "Requirementsファイル" - -#: ../source/glossary.rst:219 ../source/glossary.rst:218 -msgid "" -"A file containing a list of :term:`Requirements ` that can be " -"installed using :ref:`pip`. For more information, see the :ref:`pip` docs " -"on :ref:`pip:Requirements Files`." -msgstr "" -":ref:`pip`を用いてインストールできるように :term:`要求事項 ` を" -"記したファイル。詳しい情報は、 :ref:`pip` のドキュメントの :ref:`pip:" -"Requirementsファイル ` をみてください。" - -#: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:59 -#: ../source/glossary.rst:222 -msgid "setup.py" -msgstr "setup.py" - -#: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:80 -#: ../source/glossary.rst:223 -msgid "setup.cfg" -msgstr "setup.cfg" - -#: ../source/glossary.rst:227 ../source/glossary.rst:226 -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 ../source/glossary.rst:229 -msgid "Source Archive" -msgstr "ソースコードアーカイブ" - -#: ../source/glossary.rst:233 ../source/glossary.rst:232 -msgid "" -"An archive containing the raw source code for a :term:`Release`, prior to " -"creation of a :term:`Source Distribution ` or :term:`Built Distribution`." -msgstr "" -":term:`ソースコード配布物 ` や :term:`ビ" -"ルド配布物 ` という用語を作る前には、:term:`リリース " -"`向けに生のソースコードを収めたアーカイブのことをこう呼んでいた。" - -#: ../source/glossary.rst:237 ../source/glossary.rst:236 -msgid "Source Distribution (or \"sdist\")" -msgstr "" -"`ソースコード配布物 (またはsdist) `" - -#: ../source/glossary.rst:240 -msgid "" -"A :term:`distribution ` format (usually generated " -"using ``python -m build --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`." -msgstr "" -":ref:`pip`のようなツールでインストールする時や :term:`ビルド配布物 ` を生成する時に必要なメタデータと必須ソースコードを提供する、" -"(通常は ``python -m build --sdist`` を使って生成される) :term:`配布物 " -"` フォーマット 。" - -#: ../source/glossary.rst:245 -msgid "System Package" -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 "バージョン指定子" - -#: ../source/glossary.rst:254 -msgid "" -"The version component of a :term:`Requirement Specifier`. For example, the " -"\">=1.3\" portion of \"foo>=1.3\". Read the :ref:`Version specifier " -"specification ` for a full description of the specifiers " -"that Python packaging currently supports. Support for this specification " -"was implemented in :ref:`setuptools` v8.0 and :ref:`pip` v6.0." -msgstr "" -":term:`要求事項指定子 ` のバージョン部分。例え" -"ば、\"foo>=1.3\" の中の \">=1.3\" の部分。\n" -"Python のパッケージングで現在サポートされている識別子の完全な記述について" -"は、 :ref:`バージョン指定子の仕様 ` を読んでください。こ" -"の仕様のサポートは、 :ref:`setuptools` v8.0 と :ref:`pip` v6.0 で実装されまし" -"た。" - -#: ../source/glossary.rst:259 -msgid "Virtual Environment" -msgstr "仮想環境" - -#: ../source/glossary.rst:262 -msgid "" -"An isolated Python environment that allows packages to be installed for use " -"by a particular application, rather than being installed system wide. For " -"more information, see the section on :ref:`Creating and using Virtual " -"Environments`." -msgstr "" -"システム全体からではなく、ある特定のアプリケーションだけから使えるようにパッ" -"ケージをインストールすることができる、隔離されたPython環境。詳細は :ref:`仮想" -"環境の生成と使用 `, which is " -"intended to replace the :term:`Egg` format. Wheel is currently supported " -"by :ref:`pip`." -msgstr "" -":term:`ビルド済配布物 ` フォーマットは、 :term:`Egg` " -"フォーマットを置換することを意図して、公式の :doc:`標準仕様 ` で導入されました。Wheel は、現時点では、 :ref:" -"`pip` によってサポートされています。" - -#: ../source/glossary.rst:274 ../source/glossary.rst:271 -msgid "Working Set" -msgstr "動作可能セット" - -#: ../source/glossary.rst:277 ../source/glossary.rst:274 -msgid "" -"A collection of :term:`distributions ` available for " -"importing. These are the distributions that are on the `sys.path` variable. " -"At most, one :term:`Distribution ` for a project is " -"possible in a working set." -msgstr "" -"一連のインポート可能な :term:`配布物 `。これらは `sys." -"path` 変数から検索できる配布物です。あるプロジェクトには、高々(訳註、at most" -"ではなくat least、すくなくとも、か。)ひとつの :term:`配布物 ` が動作可能セットにあります。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:3 -msgid "Analyzing PyPI package downloads" -msgstr "PyPIパッケージのダウンロード状況の解析" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:5 -msgid "" -"This section covers how to use the public PyPI download statistics dataset " -"to learn more about downloads of a package (or packages) hosted on PyPI. For " -"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 -msgid "Background" -msgstr "背景" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:14 -msgid "PyPI does not display download statistics for a number of reasons: [#]_" -msgstr "PyPIはいくつもの理由からダウンロード統計を表示しません。:[#]_" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:16 -msgid "" -"**Inefficient to make work with a Content Distribution Network (CDN):** " -"Download statistics change constantly. Including them in project pages, " -"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 "``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)" -msgstr "PyPIにホストされていないパッケージ (比較することの妥当性を損ねる)" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:27 -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 "" -"**Not particularly useful:** Just because a project has been downloaded a " -"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 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 "公開データセット" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:42 -msgid "" -"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " -"[#]_, where they are stored as a public dataset." -msgstr "" -"別の方法としては、 `Linehaulプロジェクト `__ がダウンロードのログをPyPIから `Google BigQuery`_ [#]_ へ" -"連続的に取り出して、公開のデータセットとして保管しています。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:47 -msgid "Getting set up" -msgstr "セットアップのやり方" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:49 -msgid "" -"In order to use `Google BigQuery`_ to query the `public PyPI download " -"statistics dataset`_, you'll need a Google account and to enable the " -"BigQuery API on a Google Cloud Platform project. You can run up to 1TB of " -"queries per month `using the BigQuery free tier without a credit card " -"`__" -msgstr "" -"`Google BigQuery`_ を使って `PyPIダウンロード統計の公開データセット `_ に問い合わせを行うためには、まずGoogleア" -"カウントが必要で、Google Cloud Platform (GCP)でBigQuery APIを有効にしておく必" -"要があります。`クレジットカード登録なしのBigQuery 無料枠 `__ を使うと一ヶ月当たり1TBまでのクエリを走らせ" -"ることができます" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:55 -msgid "Navigate to the `BigQuery web UI`_." -msgstr "`BigQuery ウェブ UI `_ への道案内。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:56 -msgid "Create a new project." -msgstr "新しいプロジェクトを作成する。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:57 -msgid "" -"Enable the `BigQuery API `__." -msgstr "" -"`BigQuery API `__ を有効にする。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:60 -msgid "" -"For more detailed instructions on how to get started with BigQuery, check " -"out the `BigQuery quickstart guide `__." -msgstr "" -"BigQueryの始め方についてさらに詳しい指南が欲しい場合は、`Cloud Console を使用" -"したクイックスタート `__ を参照してください。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:66 -msgid "Data schema" -msgstr "データ構造" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:68 -msgid "" -"Linehaul writes an entry in a ``bigquery-public-data.pypi.file_downloads`` " -"table for each download. The table contains information about what file was " -"downloaded and how it was downloaded. Some useful columns from the `table " -"schema `__ include:" -msgstr "" -"それぞれのダウンロードの情報を格納した ``bigquery-public-data.pypi." -"file_downloads``テーブルについての説明をLinehaulが書きました。このテーブル" -"は、どのファイルがどのようにダウンロードされたかに関する情報を格納していま" -"す。`テーブル構造 `__ から役に" -"立つカラムをいくつか挙げると：" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:75 -msgid "Column" -msgstr "カラム" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:194 -msgid "Description" -msgstr "説明" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:29 -#: ../source/specifications/direct-url-data-structure.rst:342 -#: ../source/specifications/version-specifiers.rst:1067 -msgid "Examples" -msgstr "例" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:77 -msgid "timestamp" -msgstr "" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:77 -msgid "Date and time" -msgstr "日付と時刻" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:77 -msgid "``2020-03-09 00:33:03 UTC``" -msgstr "" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:79 -msgid "file.project" -msgstr "" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:79 -msgid "Project name" -msgstr "プロジェクト名" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:79 -msgid "``pipenv``, ``nose``" -msgstr "" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:81 -msgid "file.version" -msgstr "" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:81 -msgid "Package version" -msgstr "パッケージのバージョン" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:81 -msgid "``0.1.6``, ``1.4.2``" -msgstr "" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:83 -msgid "details.installer.name" -msgstr "" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:83 -msgid "Installer" -msgstr "インストーラ" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:83 -msgid "pip, :ref:`bandersnatch`" -msgstr "pip、 :ref:`bandersnatch`" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:85 -msgid "details.python" -msgstr "" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:85 -msgid "Python version" -msgstr "Pythonバージョン" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:85 -msgid "``2.7.12``, ``3.6.4``" -msgstr "" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:90 -msgid "Useful queries" -msgstr "役に立つクエリ" +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "``alias``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:92 -msgid "" -"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " -"button." -msgstr "" -"「クエリを新規作成」ボタンをクリックすることで `BigQuery web UI`_ 内でクエリ" -"を走らせましょう。" +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "``bdist``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:94 -msgid "" -"Note that the rows are stored in a partitioned table, which helps limit the " -"cost of queries. These example queries analyze downloads from recent history " -"by filtering on the ``timestamp`` column." -msgstr "" -"クエリのコストを削減するためにデータベースの行がパーティションされた状態で格" -"納されていることを覚えておいてください。これらの例では、``timestamp`` カラム" -"を使って絞り込むことで最近のダウンロード履歴を分析しています。" +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "``bdist_dumb``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:99 -msgid "Counting package downloads" -msgstr "パッケージのダウンロードを数える" +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "``bdist_egg``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:101 -msgid "" -"The following query counts the total number of downloads for the project " -"\"pytest\"." -msgstr "次のクエリは\"pytest\"プロジェクトのダウンロード総数を数えています。" +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "``bdist_rpm``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:116 -#: ../source/guides/analyzing-pypi-package-downloads.rst:137 -#: ../source/guides/analyzing-pypi-package-downloads.rst:165 -#: ../source/guides/analyzing-pypi-package-downloads.rst:202 -msgid "num_downloads" -msgstr "" +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "``build``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:118 -msgid "26190085" -msgstr "" +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "``build_clib``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:121 -msgid "" -"To count downloads from pip only, filter on the ``details.installer.name`` " -"column." -msgstr "" -"pipを通じてダウンロードされた数だけを数えるには、``details.installer.name``カ" -"ラムを使って抽出してください。" +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "``build_ext``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:139 -msgid "24334215" -msgstr "" +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "``build_py``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:143 -msgid "Package downloads over time" -msgstr "時系列のパッケージダウンロード数" +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "``build_scripts``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:145 -msgid "" -"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " -"filtering by this column reduces corresponding costs." -msgstr "" -"月毎のダウンロード数を数えるには、``TIMESTAMP_TRUNC``関数を使います。このカラ" -"ムを使って抽出することは、通信量を抑えることにもなります。" +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "``clean``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:165 -msgid "month" -msgstr "" +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "``dist_info``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:167 -msgid "1956741" -msgstr "1956741" +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "``easy_install``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:167 -msgid "2018-01-01" -msgstr "" +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "``editable_wheel``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:169 -msgid "2344692" -msgstr "2344692" +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "``egg_info``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:169 -msgid "2017-12-01" -msgstr "2017-12-01" +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install``" +msgstr "``install``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:171 -msgid "1730398" -msgstr "1730398" +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_data``" +msgstr "``install_data``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:171 -msgid "2017-11-01" -msgstr "2017-11-01" +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_egg_info``" +msgstr "``install_egg_info``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:173 -msgid "2047310" -msgstr "2047310" +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_headers``" +msgstr "``install_headers``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:173 -msgid "2017-10-01" -msgstr "2017-10-01" +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_lib``" +msgstr "``install_lib``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:175 -msgid "1744443" -msgstr "1744443" +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``install_scripts``" +msgstr "``install_scripts``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:175 -msgid "2017-09-01" -msgstr "2017-09-01" +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``rotate``" +msgstr "``rotate``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:177 -msgid "1916952" -msgstr "1916952" +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``saveopts``" +msgstr "``saveopts``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:177 -msgid "2017-08-01" -msgstr "2017-08-01" +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``setopt``" +msgstr "``setopt``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:181 -msgid "Python versions over time" -msgstr "時系列で見たPythonバージョン" +#: ../source/discussions/setup-py-deprecated.rst:153 +msgid "``upload_docs``" +msgstr "``upload_docs``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:157 +msgid "What about custom commands?" +msgstr "カスタムコマンドについてはどうでしょうか？" + +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" -"Extract the Python version from the ``details.python`` column. Warning: This " -"query processes over 500 GB of data." +"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 "" -"``details.python``カラムからPythonのバージョンを取り出します。警告：このクエ" -"リは500GB以上のデータを処理します。" +"同様に、カスタムコマンドの :file:`setup.py` も非推奨になっています。そのよう" +"なカスタムコマンドについては、タスクランナーツールか他の類似ツールに移植する" +"ことをお勧めします。そのようなツールの例を挙げれば: chuy、 make、 nox もしく" +"は tox、 pydoit、 pyinvoke、 taskipy、 そして thx。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:202 -msgid "python" -msgstr "python" +#: ../source/discussions/setup-py-deprecated.rst:167 +msgid "What about custom build steps?" +msgstr "カスタムビルドステップについてはどうでしょうか？" -#: ../source/guides/analyzing-pypi-package-downloads.rst:204 -msgid "3.7" -msgstr "3.7" +#: ../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/guides/analyzing-pypi-package-downloads.rst:204 -msgid "18051328726" -msgstr "18051328726" +#: ../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/guides/analyzing-pypi-package-downloads.rst:206 -msgid "3.6" -msgstr "3.6" +#: ../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/guides/analyzing-pypi-package-downloads.rst:206 -msgid "9635067203" -msgstr "9635067203" +#: ../source/discussions/setup-py-deprecated.rst:184 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "``pyproject.toml`` は必須ですか？" -#: ../source/guides/analyzing-pypi-package-downloads.rst:208 -msgid "3.8" -msgstr "3.8" +#: ../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 "" +"技術的には無くてはならないというわけではありませんが、プロジェクトがそのソー" +"スコードツリーのルート部分に :file:`pyproject.toml` ファイルを持つことは **強" +"く推奨** されています:" -#: ../source/guides/analyzing-pypi-package-downloads.rst:208 -msgid "7781904681" -msgstr "7781904681" +#: ../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/guides/analyzing-pypi-package-downloads.rst:210 -msgid "2.7" -msgstr "2.7" +#: ../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 "" +":file:`pyproject.toml` ファイルとその ``[build-system]`` テーブルが存在しない" +"場合、 :term:`ビルドフロントエンド ` にとって標準的なフォール" +"バックの振る舞いは、 :term:`ビルドバックエンド ` が " +"setuptools であると仮定することです。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:210 -msgid "6381252241" -msgstr "6381252241" +#: ../source/discussions/setup-py-deprecated.rst:205 +msgid "Why? What does it all mean?" +msgstr "どうして？一体全体どういうこと？" -#: ../source/guides/analyzing-pypi-package-downloads.rst:212 -msgid "null" +#: ../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/guides/analyzing-pypi-package-downloads.rst:212 -msgid "2026630299" -msgstr "2026630299" +#: ../source/discussions/setup-py-deprecated.rst:212 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "これについて、どこでもっと読めますか？" -#: ../source/guides/analyzing-pypi-package-downloads.rst:214 -msgid "3.5" -msgstr "3.5" +#: ../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/guides/analyzing-pypi-package-downloads.rst:214 -msgid "1894153540" -msgstr "1894153540" +#: ../source/discussions/setup-py-deprecated.rst:216 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr ":doc:`setuptools:deprecated/commands`" -#: ../source/guides/analyzing-pypi-package-downloads.rst:219 -msgid "Getting absolute links to artifacts" -msgstr "アーティファクトへの完全なリンクを得る" +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "src レイアウト対フラットレイアウト" -#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +#: ../source/discussions/src-layout-vs-flat-layout.rst:7 msgid "" -"It's sometimes helpful to be able to get the absolute links to download " -"artifacts from PyPI based on their hashes, e.g. if a particular project or " -"release has been deleted from PyPI. The metadata table includes the ``path`` " -"column, which includes the hash and artifact filename." +"The \"flat layout\" refers to organising a project's files in a folder or " +"repository, such that the various configuration files and :term:`import " +"packages ` are all in the top-level directory." msgstr "" -"例えばあるプロジェクトやリリースが PyPI から削除されてしまったような場合に、" -"ハッシュ値に基づいて PyPI からアーティファクト(訳注、そのようなプロジェクトや" -"リリース)をダウンロードすることができる完全なリンクがあれば便利な時もあるで" -"しょう。メタデータテーブルには ``path`` 列があって、ハッシュ値とアーティファ" -"クトのファイル名を保持しています。" +"「フラットレイアウト」とは、さまざまな設定ファイルや :term:`インポートパッ" +"ケージ ` をすべてトップレベルのディレクトリに置くようなやり方" +"で、プロジェクトのファイル群をひとつのフォルダまたはリポジトリに配置すること" +"です。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:227 +#: ../source/discussions/src-layout-vs-flat-layout.rst:25 msgid "" -"The URL generated here is not guaranteed to be stable, but currently aligns " -"with the URL where PyPI artifacts are hosted." +"The \"src layout\" deviates from the flat layout by moving the code that is " +"intended to be importable (i.e. ``import awesome_package``, also known as :" +"term:`import packages `) into a subdirectory. This " +"subdirectory is typically named ``src/``, hence \"src layout\"." msgstr "" -"ここで生成された URL はいつまでも存在するとは限りませんが、しかし、その時点" -"で PyPI のアーティファクトがどこに保存されているかを示す URL を含んでいます。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:240 -msgid "url" -msgstr "url" +"「src レイアウト」は、インポート可能 (すなわち ``import awesome_package`` 、" +"別名 :term:`インポートパッケージ `) にするつもりのソースコー" +"ドをサブディレクトリに置く点でフラットレイアウトとは異なります。このサブディ" +"レクトリは、典型的には ``src/`` と命名されるので、「src レイアウト」と呼ばれ" +"るのです。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 msgid "" -"https://files.pythonhosted.org/packages/" -"eb/45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" -"sampleproject-1.2.0.tar.gz" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" msgstr "" -"https://files.pythonhosted.org/packages/" -"eb/45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" -"sampleproject-1.2.0.tar.gz" +"ここで、src レイアウトとフラットレイアウトの動作の違いで重要なものを掲出して" +"おきましょう:" -#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 msgid "" -"https://files.pythonhosted.org/" -"packages/56/0a/178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" -"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." msgstr "" -"https://files.pythonhosted.org/" -"packages/56/0a/178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" -"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +"src レイアウトではそのソースコードを走らせるためにプロジェクトのインストール" +"が要求されますが、フラットレイアウトではそのようなことはありません。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 msgid "" -"https://files.pythonhosted.org/" -"packages/63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" -"sampleproject_nomura-1.2.0.tar.gz" +"This means that the src layout involves an additional step in the " +"development workflow of a project (typically, an :doc:`editable installation " +"` is used for development and a " +"regular installation is used for testing)." msgstr "" -"https://files.pythonhosted.org/" -"packages/63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" -"sampleproject_nomura-1.2.0.tar.gz" +"これが意味するところは、src レイアウトの場合にはプロジェクトの開発ワークフ" +"ローに追加的なステップ (典型的には、開発には :doc:`編集可能なインストール " +"` を使い、テストには通常のインストール" +"を用いる) が必要になるということです。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 msgid "" -"https://files.pythonhosted.org/packages/21/" -"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" -"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." msgstr "" -"https://files.pythonhosted.org/packages/21/" -"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" -"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +"src レイアウトを採用することは、今まさに開発中のソースコードを使ってしまうと" +"いう事故を防ぐことを助けます。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 msgid "" -"https://files.pythonhosted.org/" -"packages/6f/5b/2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" -"sampleproject-1.3.1.tar.gz" +"This is relevant since the Python interpreter includes the current working " +"directory as the first item on the import path. This means that if an import " +"package exists in the current working directory with the same name as an " +"installed import package, the variant from the current working directory " +"will be used. This can lead to subtle misconfiguration of the project's " +"packaging tooling, which could result in files not being included in a " +"distribution." 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 "注意書き" +"Python インタープリタはカレントワーキングディレクトリをインポートパスの先頭に" +"含むので、これは妥当なことです。これが意味するところは、もしインストール済み" +"のパッケージと同名のものがカレントワーキングディレクトリに存在するならば、カ" +"レントワーキングディレクトリにあるものが使われるであろうということです。これ" +"によって、配布物に一部ファイル群が含まれない結果に終わるという、プロジェクト" +"のパッケージングツールの微妙な誤設定をもたらしかねません。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 msgid "" -"In addition to the caveats listed in the background above, Linehaul suffered " -"from a bug which caused it to significantly under-report download statistics " -"prior to July 26, 2018. Downloads before this date are proportionally " -"accurate (e.g. the percentage of Python 2 vs. Python 3 downloads) but total " -"numbers are lower than actual by an order of magnitude." +"The src layout helps avoid this by keeping import packages in a directory " +"separate from the root directory of the project, ensuring that the installed " +"copy is used." msgstr "" -"上記の背景に列挙した注意書きに加えて、Linehaulは、極端に過小報告されていたダ" -"ウンロード統計の原因となったバグに2018年7月26日まで悩まされていました。この日" -"より前のダウンロード数については、比率の点(例えばPython2とPython3の百分率)で" -"は正確ですが、絶対数の点では桁が異なるほどに過小です。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:265 -msgid "Additional tools" -msgstr "その他のツール" +"src レイアウトを使えば、パッケージ群をプロジェクトのルートディレクトリとは異" +"なるディレクトリに置くので、インストール済みのパッケージの方を使用することが" +"保証され、このような誤設定を避ける助けになります。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +#: ../source/discussions/src-layout-vs-flat-layout.rst:70 msgid "" -"Besides using the BigQuery console, there are some additional tools which " -"may be useful when analyzing download statistics." +"The src layout helps enforce that an :doc:`editable installation ` is only able to import files that were meant to " +"be importable." msgstr "" -"BigQueryコンソールを用いる他に、ダウンロード統計を分析する際に役に立つと思わ" -"れるツールがいくつかあります。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:271 -msgid "``google-cloud-bigquery``" -msgstr "``google-cloud-bigquery``" +"src レイアウトを使うことで、インポートしようと意図した :doc:`編集可能なインス" +"トール ` だけをインポートするように強" +"制することを助けます。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 msgid "" -"You can also access the public PyPI download statistics dataset " -"programmatically via the BigQuery API and the `google-cloud-bigquery`_ " -"project, the official Python client library for BigQuery." +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." msgstr "" -"BigQuery APIとBigQuery用の公式Pythonクライアントである `google-cloud-" -"bigquery`_ プロジェクトを使って、プログラムからPyPIの公開ダウンロード統計デー" -"タセットにアクセスすることもできます。" - -#: ../source/guides/analyzing-pypi-package-downloads.rst:301 -msgid "``pypinfo``" -msgstr "``pypinfo``" +"これは、編集可能なインストール (のパッケージ) がインポートパスにそのディレク" +"トリを追加するように動く `パス設定ファイル `_ を使って実装されている場合に、特に適切です。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +#: ../source/discussions/src-layout-vs-flat-layout.rst:78 msgid "" -"`pypinfo`_ is a command-line tool which provides access to the dataset and " -"can generate several useful queries. For example, you can query the total " -"number of download for a package with the command ``pypinfo package_name``." +"The flat layout would add the other project files (eg: ``README.md``, ``tox." +"ini``) and packaging/tooling configuration files (eg: ``setup.py``, " +"``noxfile.py``) on the import path. This would make certain imports work in " +"editable installations but not regular installations." msgstr "" -"`pypinfo`_ はデータセットにアクセスして、役に立つクエリをいくつか生成する機能" -"を提供するコマンドラインツールです。例えば、``pypinfo package_name``を実行す" -"れば、そのパッケージのダウンロード総数を問い合わせることができます。" +"フラットレイアウトでは、インポートパスに他のプロジェクトファイル群 (例えば " +"``README.md`` や ``tox.ini``) や、パッケージング/ツール使用の設定ファイル (例" +"えば ``setup.py`` や ``noxfile.py``) を追加します。こうすることによって、ある" +"インポートが、通常のインストールではなくて編集可能なインストールの側を使うこ" +"とを確実にするでしょう。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:307 -msgid "Install `pypinfo`_ using pip." -msgstr "pipを用いて `pypinfo`_ をインストール。" +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:310 +msgid "Versioning" +msgstr "バージョニング" -#: ../source/guides/analyzing-pypi-package-downloads.rst:313 -msgid "Usage:" -msgstr "使い方：" +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" +"この議論では、 Python パッケージのバージョニングについてあらゆる角度からカ" +"バーします。" -#: ../source/guides/analyzing-pypi-package-downloads.rst:329 -msgid "``pandas-gbq``" -msgstr "``pandas-gbq``" +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "正当なバージョン番号" -#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +#: ../source/discussions/versioning.rst:14 msgid "" -"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but in order to be compatible with tools " +"like :ref:`pip`, all of them are required to comply with a flexible format " +"for version identifiers, for which the authoritative reference is the :ref:" +"`specification of version specifiers `. Here are some " +"examples of version numbers [#version-examples]_:" msgstr "" -"`pandas-bbq`_ プロジェクトを使えば `Pandas`_ 経由でクエリ結果を参照することが" -"できます。" +"相異なるPythonプロジェクトがそれぞれの事情に合わせて異なるバージョン体系を採" +"用することは構いませんが、しかし、:ref:`pip` のようなツールとの互換性を保つた" +"めには、バージョン識別子のための自由度の高いフォーマット、その権威ある参照先" +"は :ref:`バージョン識別子仕様 ` ですが、これに準拠するこ" +"とが要求されます。ここではバージョン番号のいくつかの例を紹介しましょう " +"[#version-examples]_:" -#: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/dependency-specifiers.rst:487 -msgid "References" -msgstr "参考文献" +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "簡明なバージョン (最終的なリリース): ``1.2.0``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:337 -msgid "" -"`PyPI Download Counts deprecation email `__" -msgstr "" -"`PyPI ダウンロード統計を非推奨とするメール (PyPI Download Counts deprecation " -"email) `__" +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "開発リリース: ``1.2.0.dev1``" -#: ../source/guides/analyzing-pypi-package-downloads.rst:338 -msgid "" -"`PyPI BigQuery dataset announcement email `__" -msgstr "" -"`PyPI BigQueryデータセットをアナウンスするメール (PyPI BigQuery dataset " -"announcement email) `__" +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "アルファリリース: ``1.2.0a1``" -#: ../source/guides/creating-and-discovering-plugins.rst:3 -msgid "Creating and discovering plugins" -msgstr "プラグイン作成と発見" +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "ベータリリース: ``1.2.0b1``" -#: ../source/guides/creating-and-discovering-plugins.rst:5 +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "リリース候補: ``1.2.0rc1``" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "ポストリリース: ``1.2.0.post1``" + +#: ../source/discussions/versioning.rst:27 msgid "" -"Often when creating a Python application or library you'll want the ability " -"to provide customizations or extra features via **plugins**. Because Python " -"packages can be separately distributed, your application or library may want " -"to automatically **discover** all of the plugins available." +"A post-release of an alpha release (possible, but discouraged): ``1.2.0a1." +"post1``" msgstr "" -"Pythonのアプリケーションまたはライブラリを作成する時には、カスタマイズができ" -"るようにしたり **プラグイン** を通じて機能を追加できるようにしたりすることが" -"しばしばあります。Pythonのパッケージは別々に配布できますので、あなたのアプリ" -"ケーションまたはライブラリが利用可能なすべてのプラグインを自動的に **探し出す" -"** ようにしたくなるかもしれません。" - -#: ../source/guides/creating-and-discovering-plugins.rst:10 -msgid "There are three major approaches to doing automatic plugin discovery:" -msgstr "プラグインの自動検出には大きく分けて３個の実現方法があります。" +"アルファリリースのポストリリース (こういうことも可能ではあるが非推奨): " +"``1.2.0a1.post1``" -#: ../source/guides/creating-and-discovering-plugins.rst:12 -msgid "`Using naming convention`_." -msgstr "`命名規則を用いるやり方 `_ 。" +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "二つの部分からのみ構成される簡明なバージョン: ``23.12``" -#: ../source/guides/creating-and-discovering-plugins.rst:13 -msgid "`Using namespace packages`_." -msgstr "`namespaceパッケージを用いるやり方 `_ 。" +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "たったひとつの部分から構成される簡明なバージョン: ``42``" -#: ../source/guides/creating-and-discovering-plugins.rst:14 -msgid "`Using package metadata`_." -msgstr "`パッケージのメタデータを用いるやり方 `_ 。" +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch: ``1!1.0``" +msgstr "エポック付きのバージョン: ``1!1.0``" -#: ../source/guides/creating-and-discovering-plugins.rst:18 -msgid "Using naming convention" -msgstr "命名規則を用いるやり方" +#: ../source/discussions/versioning.rst:32 +msgid "" +"Projects can use a cycle of pre-releases to support testing by their users " +"before a final release. In order, the steps are: alpha releases, beta " +"releases, release candidates, final release. Pip and other modern Python " +"package installers ignore pre-releases by default when deciding which " +"versions of dependencies to install, unless explicitly requested (e.g., with " +"``pip install pkg==1.1a3`` or ``pip install --pre pkg``)." +msgstr "" +"プロジェクトにおいては、最終的なリリースの前にいくつかのプレリリースのサイク" +"ルを置くことで既存ユーザによる試験をサポートすることができます。その段階は、" +"アルファリリース、ベータリリース、リリース候補、最終的なリリースの順です。 " +"pip や他の近代的な Python パッケージインストーラは、依存関係にあるパッケージ" +"のどのバージョンをインストールするかを決定する際、 (例えば ``pip install " +"pkg==1.1a3`` とか ``pip install --pre pkg`` のように) 明示的に要求されていな" +"い限りデフォルト設定ではプレリリース群を無視します。" -#: ../source/guides/creating-and-discovering-plugins.rst:20 +#: ../source/discussions/versioning.rst:39 msgid "" -"If all of the plugins for your application follow the same naming " -"convention, you can use :func:`pkgutil.iter_modules` to discover all of the " -"top-level modules that match the naming convention. For example, `Flask`_ " -"uses the naming convention ``flask_{plugin_name}``. If you wanted to " -"automatically discover all of the Flask plugins installed:" +"The purpose of development releases is to support releases made early during " +"a development cycle, for example, a nightly build, or a build from the " +"latest source in a Linux distribution." msgstr "" -"あなたのアプリケーション用のすべてのプラグインが命名規則に従うのであれば、 :" -"func:`pkgutil.iter_modules` を用いて命名規則に合致するトップレベルのすべての" -"モジュールを発見することができます。例えば、 `Flask`_ は命名規則として " -"``flask_{plugin_name}`` を使います。もし、すべてのインストール済みFlask用プラ" -"グインを発見したいのであれば：" +"開発リリースの目的は、例えば夜毎のビルド のように開発サイクル" +"の早い時期にリリースを行うことや、Linux ディストリビューションの最新のソース" +"コードからビルドを行うことです。" -#: ../source/guides/creating-and-discovering-plugins.rst:38 +#: ../source/discussions/versioning.rst:43 msgid "" -"If you had both the `Flask-SQLAlchemy`_ and `Flask-Talisman`_ plugins " -"installed then ``discovered_plugins`` would be:" +"Post-releases are used to address minor errors in a final release that do " +"not affect the distributed software, such as correcting an error in the " +"release notes. They should not be used for bug fixes; these should be done " +"with a new final release (e.g., incrementing the third component when using " +"semantic versioning)." msgstr "" -"もしあなたが `Flask-SQLAlchemy`_ と `Flask-Talisman`_ のふたつのプラグインを" -"インストールしてあるなら、 ``discovered_plugins`` は次のようになるでしょう：" +"ポストリリースは、リリースノート内のエラーのように配布されたソフトウェアに大" +"きな悪影響を与えないようなファイナルリリースの軽微なエラーを修正するために使" +"われます。バグ修正のために使うべきではなく、それは新たな (即ち、セマンティッ" +"クバージョニングを使っているなら第３要素を１だけ増加させた) ファイナルリリー" +"スで行うべきです。" -#: ../source/guides/creating-and-discovering-plugins.rst:48 +#: ../source/discussions/versioning.rst:49 msgid "" -"Using naming convention for plugins also allows you to query the Python " -"Package Index's :ref:`simple repository API ` for all " -"packages that conform to your naming convention." +"Finally, epochs, a rarely used feature, serve to fix the sorting order when " +"changing the versioning scheme. For example, if a project is using calendar " +"versioning, with versions like 23.12, and switches to semantic versioning, " +"with versions like 1.0, the comparison between 1.0 and 23.12 will go the " +"wrong way. To correct this, the new version numbers should have an explicit " +"epoch, as in \"1!1.0\", in order to be treated as more recent than the old " +"version numbers." msgstr "" -"プラグインの命名規則を用いることで、あなたの命名規則に従うすべてのパッケージ" -"についてPython パッケージインデックスの :ref:`simple repository API ` から検索することもできるようになります。" +"最後に、エポックは、稀にしか使われない機能ですが、バージョニングの方法を変更" +"するときに順序を訂正するために使われます。例えば、 23.12 のようなカレンダー" +"バージョニングを使っているプロジェクトが 1.0 のようなセマンティックバージョニ" +"ングに移行するような場合に、 1.0 と 23.12 の間の比較は誤った結果になるでしょ" +"う。これを訂正するために、明示的に示された \"1!1.0\" のようなエポックを持つこ" +"とで、新しいバージョン番号が古いバージョン番号よりもより最近のものとして扱わ" +"れるようにするべきです。" -#: ../source/guides/creating-and-discovering-plugins.rst:58 -msgid "Using namespace packages" -msgstr "namespaceパッケージを用いるやり方" +#: ../source/discussions/versioning.rst:59 +msgid "Semantic versioning vs. calendar versioning" +msgstr "セマンティックバージョニング対カレンダーバージョニング" -#: ../source/guides/creating-and-discovering-plugins.rst:60 +#: ../source/discussions/versioning.rst:61 msgid "" -":doc:`Namespace packages ` can be used to " -"provide a convention for where to place plugins and also provides a way to " -"perform discovery. For example, if you make the sub-package ``myapp." -"plugins`` a namespace package then other :term:`distributions ` can provide modules and packages to that namespace. Once " -"installed, you can use :func:`pkgutil.iter_modules` to discover all modules " -"and packages installed under that namespace:" +"A versioning scheme is a formalized way to interpret the segments of a " +"version number, and to decide which should be the next version number for a " +"new release of a package. Two versioning schemes are commonly used for " +"Python packages, semantic versioning and calendar versioning." msgstr "" -":doc:`Namespace パッケージ ` を使えば、プラグイ" -"ンをどこに配置するかに関する規則や、発見するための方法も提供できます。例え" -"ば、あなたが名前空間を決めるサブパッケージ ``myapp.plugins`` を作成したら、そ" -"の名前空間に他の :term:`配布物 ` がモジュールやパッケー" -"ジを配置することができます。インストールが終われば、あなたは :func:`pkgutil." -"iter_modules` を用いてインストール済みの全てのモジュールやパッケージをその名" -"前空間で発見できるでしょう。" +"バージョニング方法とは、バージョン番号の断片を翻訳するために決められたやり方" +"で、パッケージの新しいリリースように次のバージョン番号がどのようなものになる" +"べきかを決めるやり方です。Python パッケージにしばしば用いられる二つのバージョ" +"ニング方法は、セマンティックバージョニングとカレンダーバージョニングです。" -#: ../source/guides/creating-and-discovering-plugins.rst:88 +#: ../source/discussions/versioning.rst:68 msgid "" -"Specifying ``myapp.plugins.__path__`` to :func:`~pkgutil.iter_modules` " -"causes it to only look for the modules directly under that namespace. For " -"example, if you have installed distributions that provide the modules " -"``myapp.plugins.a`` and ``myapp.plugins.b`` then ``discovered_plugins`` in " -"this case would be:" +"The decision which version number to choose is up to a project's maintainer. " +"This effectively means that version bumps reflect the maintainer's view. " +"That view may differ from the end-users' perception of what said formalized " +"versioning scheme promises them." msgstr "" -":func:`~pkgutil.iter_modules` に ``myapp.plugins.__path__`` を指定すると、そ" -"の名前空間の直下にあるモジュールだけを探索するようになります。例えば、あなた" -"がモジュールの ``myapp.plugins.a`` と ``myapp.plugins.b`` を提供する配布物を" -"インストールしているとしたら、 ``discovered_plugins`` は次のようになるでしょ" -"う：" +"どのようなバージョン番号を選択するべきかの決定権はプロジェクトのメンテナに委" +"ねられています。これは、バージョン上げにメンテナの観点を反映しているというこ" +"とを実質的に意味します。そのような観点は、バージョニング方法が約束するやり方" +"についてのエンドユーザの受け取り方とは異なるかも知れません。" -#: ../source/guides/creating-and-discovering-plugins.rst:100 +#: ../source/discussions/versioning.rst:74 msgid "" -"This sample uses a sub-package as the namespace package (``myapp.plugins``), " -"but it's also possible to use a top-level package for this purpose (such as " -"``myapp_plugins``). How to pick the namespace to use is a matter of " -"preference, but it's not recommended to make your project's main top-level " -"package (``myapp`` in this case) a namespace package for the purpose of " -"plugins, as one bad plugin could cause the entire namespace to break which " -"would in turn make your project unimportable. For the \"namespace sub-" -"package\" approach to work, the plugin packages must omit the :file:" -"`__init__.py` for your top-level package directory (``myapp`` in this case) " -"and include the namespace-package style :file:`__init__.py` in the namespace " -"sub-package directory (``myapp/plugins``). This also means that plugins " -"will need to explicitly pass a list of packages to :func:`setup`'s " -"``packages`` argument instead of using :func:`setuptools.find_packages`." +"There are known exceptions for selecting the next version number. The " +"maintainers may consciously choose to break the assumption that the last " +"version segment only contains backwards-compatible changes. One such case is " +"when security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." msgstr "" -"この例ではサブパッケージを名前空間を決めるパッケージ(``myapp.plugins``)として" -"使っていますが、トップレベルのパッケージをこの(``myapp_plugins``のような)目的" -"に用いることも可能です。名前空間をどのようにして決めるかは好みの問題ですが、" -"あなたのプロジェクトのトップレベルのパッケージ(この場合では``myapp``)をプラグ" -"インの名前空間を決めるために用いると、全体の名前空間を破壊するようなプラグイ" -"ンがひとつあるだけで、あなたのプロジェクトをインポートすることができなくなる" -"のでお勧めしません。「名前空間を決めるサブパッケージ」の手法がうまく動作する" -"ためには、プラグインパッケージ側のトップレベルパッケージのディレクトリ(この場" -"合には``myapp``)に :file:`__init__.py` が存在してはいけませんし、名前空間を決" -"めるサブパッケージのディレクトリ(``myapp/plugins``)にある :file:`__init__.py`" -"をプラグインパッケージ側でインクルードしなければなりません。これはまた、 プラ" -"グインの側で:func:`setuptools.find_packages` を使うのではなく、パッケージの名" -"前を :func:`setup`の ``packages`` 引数に明示的に渡す必要がある、ということを" -"意味しています。" +"次のバージョン番号を選定する上で既知の例外があります。保守者は、最後のバー" +"ジョン断片が後方互換性を保つための変更だけを含むという想定を破るような選択を" +"意識的に行っても構いません。そのような場合の一つは、セキュリティ上の脆弱性を" +"修正する必要がある時です。セキュリティリリースは、しばしば、パッチバージョン" +"として提供されますが、そうすると必然的にここで述べているような変更をもたらし" +"ます。" -#: ../source/guides/creating-and-discovering-plugins.rst:114 +#: ../source/discussions/versioning.rst:84 +#: ../source/specifications/version-specifiers.rst:721 +msgid "Semantic versioning" +msgstr "セマンティックバージョニング" + +#: ../source/discussions/versioning.rst:86 msgid "" -"Namespace packages are a complex feature and there are several different " -"ways to create them. It's highly recommended to read the :doc:`packaging-" -"namespace-packages` documentation and clearly document which approach is " -"preferred for plugins to your project." +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" msgstr "" -"名前空間を決めるパッケージは込み入った機能で、いくつかの異なる作成方法があり" -"ます。 :doc:`packaging-namespace-packages` 文書を読むとともに、あなたのプロ" -"ジェクト用のプラグインとしてはどちらの手法が好ましいのかを明白に文書化してお" -"くことを強くお勧めします。" +"*セマンティックバージョニング* (または SemVer) のアイデアは、３個の部分から構" +"成されるバージョン番号、つまり *major.minor.patch* を用いることで、プロジェク" +"トの作者は以下のように各段階の数字を増やします:" -#: ../source/guides/creating-and-discovering-plugins.rst:122 -msgid "Using package metadata" -msgstr "パッケージのメタデータを用いるやり方" +#: ../source/discussions/versioning.rst:89 +msgid "*major* when they make incompatible API changes," +msgstr "APIの変更で互換性を失う時には *major* 番号、" -#: ../source/guides/creating-and-discovering-plugins.rst:124 +#: ../source/discussions/versioning.rst:90 msgid "" -"Packages can have metadata for plugins described in the :ref:`entry-points`. " -"By specifying them, a package announces that it contains a specific kind of " -"plugin. Another package supporting this kind of plugin can use the metadata " -"to discover that plugin." +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "後方互換性を保ったままで新機能を追加する場合には *minor* を、そして" + +#: ../source/discussions/versioning.rst:91 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "後方互換性を維持したままのバグ修正の場合には *patch* を増加させます。" + +#: ../source/discussions/versioning.rst:93 +msgid "" +"A majority of Python projects use a scheme that resembles semantic " +"versioning. However, most projects, especially larger ones, do not strictly " +"adhere to semantic versioning, since many changes are technically breaking " +"changes but affect only a small fraction of users. Such projects tend to " +"increment the major number when the incompatibility is high, or to signal a " +"shift in the project, rather than for any tiny incompatibility [#semver-" +"strictness]_. Conversely, a bump of the major version number is sometimes " +"used to signal significant but backwards-compatible new features." msgstr "" -"パッケージは、 :ref:`entry-points` に記述されたプラグインのためのメタデータを" -"持つことができます。それを指定することで、パッケージが特定の種類のプラグイン" -"を含んでいることをアナウンスします。そのメタデータを使って、同じ種類のプラグ" -"インをサポートする別のパッケージがそのプラグインを検出するのに使うことができ" +"Python プロジェクトの大多数は、セマンティックバージョニングに似た方式を使って" +"います。しかしながら、ほとんどのプロジェクト、とりわけ大規模なものでは、多く" +"の変更が技術的には互換性を保たないけれども少数のユーザにしか影響を与えないの" +"で、セマンティックバージョニングに厳密に従うことはしていません。そのようなプ" +"ロジェクトでは、小さな非互換性であってもいつも major 番号を増やす [#semver-" +"strictness]_ というよりは、非互換性が高い場合やプロジェクトの方向性が変わるこ" +"とを示す時に増やす傾向にあります。逆に、時には、重要ではあるが後方互換性を損" +"なわない新機能に注目を集めるために major バージョン番号を増加させることもあり" "ます。" -#: ../source/guides/creating-and-discovering-plugins.rst:128 +#: ../source/discussions/versioning.rst:103 msgid "" -"For example if you have a package named ``myapp-plugin-a`` and it includes " -"the following in its ``pyproject.toml``:" +"For those projects that do use strict semantic versioning, this approach " +"allows users to make use of :ref:`compatible release version specifiers " +"`, with the ``~=`` operator. For " +"example, ``name ~= X.Y`` is roughly equivalent to ``name >= X.Y, == X.*``, i." +"e., it requires at least release X.Y, and allows any later release with " +"greater Y as long as X is the same. Likewise, ``name ~= X.Y.Z`` is roughly " +"equivalent to ``name >= X.Y.Z, == X.Y.*``, i.e., it requires at least X.Y.Z " +"and allows a later release with same X and Y but higher Z." msgstr "" -"例えば、``myapp-plugin-a`` という名前のパッケージが存在して、その " -"``pyproject.toml`` に次のものを含む場合：" +"厳密なセマンティックバージョニングを採用しているプロジェクトでは、このアプ" +"ローチによってユーザが ``~=`` 演算子を用いた :ref:`互換リリースバージョン指定" +"子 ` を使うことができるようになりま" +"す。例えば、 ``name ~= X.Y`` は ``name >= X.Y, == X.*`` と大まかに言って等価" +"で、つまり、少なくともリリース X.Y を要求していて X が同じである限りは Y が大" +"きくなった後続リリースを許容するということです。同様に、 ``name ~= X.Y.Z`` は" +"大まかに ``name >= X.Y.Z, == X.Y.*`` と等価で、少なくとも X.Y.Z を要求してい" +"て X と Y が同じである限り Z が大きくなった後続のリリースを許容するということ" +"です。" + +#: ../source/discussions/versioning.rst:112 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" +"セマンティックバージョニングを採用しているPythonプロジェクトでは、 `セマン" +"ティックバージョニング 2.0.0 仕様書 `_ の第１節から第８節までを甘受" +"すべきです。" -#: ../source/guides/creating-and-discovering-plugins.rst:136 +#: ../source/discussions/versioning.rst:115 msgid "" -"Then you can discover and load all of the registered entry points by using :" -"func:`importlib.metadata.entry_points` (or the backport_ " -"``importlib_metadata >= 3.6`` for Python 3.6-3.9):" +"The popular :doc:`Sphinx ` documentation generator is an " +"example project that uses strict semantic versioning (:doc:`Sphinx " +"versioning policy `). The famous :doc:" +"`NumPy ` scientific computing package explicitly uses \"loose\" " +"semantic versioning, where releases incrementing the minor version can " +"contain backwards-incompatible API changes (:doc:`NumPy versioning policy " +"`)." msgstr "" -"そして、 :func:`import lib.metadata.entry_points` (あるいはPython 3.6-3.9用" -"の backport_``import lib_metadata>=3.6``)を使うことで、登録されたエントリポイ" -"ントを全て検出することができます。" +"人気のあるドキュメンテーションジェネレータである :doc:`Sphinx ` は、厳密なセマンティックバージョニング (:doc:`Sphinx バージョニング方" +"針 `) を採用しているプロジェクトの例です。" +"有名な科学計算パッケージである :doc:`NumPy ` は、マイナーバー" +"ジョンの更新でも後方互換性のない API 変更を含む場合がある (:doc:`NumPy バー" +"ジョニング方針 `) ということで、明示的に \"ゆる" +"い\" セマンティックバージョニングを採用しています。" -#: ../source/guides/creating-and-discovering-plugins.rst:151 +#: ../source/discussions/versioning.rst:124 +msgid "Calendar versioning" +msgstr "カレンダーバージョニング" + +#: ../source/discussions/versioning.rst:126 msgid "" -"In this example, ``discovered_plugins`` would be a collection of type :class:" -"`importlib.metadata.EntryPoint`:" +"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 "" -"この例では、 ``discovered_plugins`` は :class:`import lib.metadata." -"EntryPoint` 型の(オブジェクトの)集合となるでしょう。" +"セマンティックバージョニングはすべてのプロジェクト向きと言うわけではなく、例" +"えば定期的なリリースサイクルに従う場合や、ある機能を削除する前に何世代にもわ" +"たるリリースで非推奨(deprecation)の警告を出すような場合には適していないかもし" +"れません。" -#: ../source/guides/creating-and-discovering-plugins.rst:160 +#: ../source/discussions/versioning.rst:130 msgid "" -"Now the module of your choice can be imported by executing " -"``discovered_plugins['a'].load()``." +"A key advantage of date-based versioning, or `calendar versioning " +"`_ (CalVer), is that it is straightforward to tell how old the base " +"feature set of a particular release is given just the version number." msgstr "" -"今や、``discovered_plugins['a'].load()`` を実行することで、あなたが選んだモ" -"ジュールをインポートすることができます。" +"`カレンダーバージョニング `_ (CalVer) の最大の利点は、バージョン番号" +"を見ただけで基盤になっている機能セットがどれほど古いのかが直截にわかることで" +"す。" -#: ../source/guides/creating-and-discovering-plugins.rst:163 +#: ../source/discussions/versioning.rst:134 msgid "" -"The ``entry_point`` specification in :file:`setup.py` is fairly flexible and " -"has a lot of options. It's recommended to read over the entire section on :" -"doc:`entry points ` ." +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." msgstr "" -":file:`setup.py` における ``entry_points`` の指定はかなり自由度が高く、オプ" -"ションがたくさんあります。 :doc:`entry_point ` の全部のセクションに目を通すことをお勧めします。" +"カレンダーバージョン番号は、典型的には *年.月* (例えば2023年12月に対して " +"23.12) の形を取ります。" -#: ../source/guides/creating-and-discovering-plugins.rst:167 +#: ../source/discussions/versioning.rst:137 msgid "" -"Since this specification is part of the :doc:`standard library `, most packaging tools other than setuptools " -"provide support for defining entry points." +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." 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 "期限切れのもの" +"標準的な Python パッケージインストーラである :doc:`Pip ` はカレン" +"ダーバージョニングを採用しています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:8 -msgid "2023-12-14" -msgstr "2023-12-14" +#: ../source/discussions/versioning.rst:142 +msgid "Other schemes" +msgstr "他の方法" -#: ../source/guides/distributing-packages-using-setuptools.rst:10 +#: ../source/discussions/versioning.rst:144 msgid "" -"This section covers some additional details on configuring, packaging and " -"distributing Python projects with ``setuptools`` that aren't covered by the " -"introductory tutorial in :doc:`/tutorials/packaging-projects`. It still " -"assumes that you are already familiar with the contents of the :doc:`/" -"tutorials/installing-packages` page." +"Serial versioning refers to the simplest possible versioning scheme, which " +"consists of a single number incremented every release. 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 "" -"この節では、 ``setuptools`` を使ったPythonパッケージの設定・パッケージング・" -"配布方法について、 :doc:`/tutorials/packaging-projects`_ の入門的なチュートリ" -"アルでは触れていないような追加的な詳細を説明します。あなたが既に :doc:`/" -"tutorials/installing-packages` ページの内容については慣れ親しんでいるものと仮" -"定して進めます。" +"一連番号によるバージョン付与は、リリースの度に増加する単一の数字で構成されて" +"いて、可能な限り単純なバージョニング方法であると見なされています。一連番号に" +"よるバージョン付与は開発者にとってはとても管理しやすい反面、一連番号による" +"バージョン番号を見てもAPIの後方互換性に関する情報がほとんど又は全くわからない" +"ので、ユーザにとっては追跡するのが最も困難です。" -#: ../source/guides/distributing-packages-using-setuptools.rst:16 +#: ../source/discussions/versioning.rst:150 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." +"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 "" -"この節は、Pythonプロジェクトの開発についての全体的なベストプラクティスを説明" -"しているわけではありません。例えば、バージョン管理や文書化、あるいは試験につ" -"いて、手引きとなったりツールを推奨するようなことはありません。" +"上に述べた方式を組み合わせて用いることもできます。例えば、日付ベースのバー" +"ジョン付与と一連番号によるバージョン付与を組み合わせて *year.month* 型のバー" +"ジョン番号付与方式を作り出して、バージョン番号がリリース年を示すけれどもその" +"年の中のどのリリースサイクルかを特定することについてはあまり気にしていないと" +"いうプロジェクトもあるでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:20 +#: ../source/discussions/versioning.rst:158 +#: ../source/specifications/version-specifiers.rst:114 +msgid "Local version identifiers" +msgstr "ローカルのバージョン指定子" + +#: ../source/discussions/versioning.rst:160 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." +"Public version identifiers are designed to support distribution via :term:" +"`PyPI `. Python packaging tools also support " +"the notion of a :ref:`local version identifier `, " +"which can be used to identify local development builds not intended for " +"publication, or modified variants of a release maintained by a redistributor." msgstr "" -"より詳しい参考文献としては、:ref:`setuptools` の説明文書の中の :std:doc:`パッ" -"ケージのビルドと配布 ` を挙げておきますが、推奨事" -"項のいくつかはもはや古くなっているかもしれません。喰い違いがあった場合には、" -"Python パッケージングユーザガイドの推奨事項を優先してください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:28 -msgid "Requirements for packaging and distributing" -msgstr "パッケージングと配布に対する要求事項" +"公的バージョン識別子は、 :term:`PyPI ` を通じた" +"配布をサポートするように設計されています。Pythonのパッケージングツール群は、" +"ローカルでの開発でビルドごとの識別子や再配布者が維持管理している変種のリリー" +"スの識別子として用いるような :ref:`局所的バージョン識別子 ` の考え方もサポートします。" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/discussions/versioning.rst:166 msgid "" -"First, make sure you have already fulfilled the :ref:`requirements for " -"installing packages `." +"A local version identifier takes the form of a public version identifier, " +"followed by \"+\" and a local version label. For example, a package with " +"Fedora-specific patches applied could have the version \"1.2.1+fedora.4\". " +"Another example is versions computed by setuptools-scm_, a setuptools plugin " +"that reads the version from Git data. In a Git repository with some commits " +"since the latest release, setuptools-scm generates a version like \"0.5." +"dev1+gd00980f\", or if the repository has untracked changes, like \"0.5." +"dev1+gd00980f.d20231217\"." msgstr "" -"最初に、あなたが既に :ref:`パッケージをインストールする際の要求事項 " -"` を満たしていることを確実にしてください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:32 -msgid "Install \"twine\" [1]_:" -msgstr "\"twine\"をインストールする [1]_:" +"ローカルバージョン識別子は、公的バージョン識別子の後ろに \"+\" とローカルバー" +"ジョンラベルを並べた形を採ります。例えば、Fedora に特有のパッチが適用された" +"パッケージは、 \"1.2.1+fedora.4\" といったバージョンになるという具合です。別" +"の例としては、 setuptools-scm_ によって計算されたバージョンで、Git のデータか" +"らバージョンを読み取る setuptools プラグインによるものです。最新のリリース以" +"後に幾つかのコミットがなされた Git リポジトリでは setuptools-scm は \"0.5." +"dev1+gd00980f\" のようなバージョンを生成することもありますし、トラックされて" +"いない変更のあるリポジトリなら \"0.5.dev1+00980f.d20231217\" のようになること" +"があります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:46 +#: ../source/discussions/versioning.rst:178 msgid "" -"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " -"`)." +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." msgstr "" -"あなたのプロジェクトの :term:`配布物 ` を :term:`PyPI " -"` にアップロードする( :ref:`後述 ` )ためにこれが必要になるでしょう。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:52 -msgid "Configuring your project" -msgstr "あなたのプロジェクトを設定する" - -#: ../source/guides/distributing-packages-using-setuptools.rst:56 -msgid "Initial files" -msgstr "最初に必要なファイル群" +"普通でないバージョン番号のいくつかの例が Seth Larson によって `ブログポスト " +"`_ に挙げられています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:61 +#: ../source/discussions/versioning.rst:181 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 `_." +"For some personal viewpoints on this issue, see these blog posts: `by Hynek " +"Schlawak `_, `by Donald Stufft `_, `by Bernát Gábor `_, `by Brett Cannon " +"`_. For a humoristic take, read about ZeroVer_." msgstr "" -"最重要のファイルは、あなたのプロジェクトのディレクトリの一番上(ルート)にあ" -"る :file:`setup.py` です。`PyPA サンプルプロジェクト `_ の `setup.py `_ に具体例がありま" -"す。" +"この問題に関する個人的な観点については、次のようなブログポストを見てくださ" +"い: `Hynek Schlawak によるもの `_ ・ `Donald Stufft " +"によるもの `_ ・ `Bernát Gábor によるもの `_ ・ `Brett Cannon によるもの `_ 。ユー" +"モラスなものが良ければ、 ZeroVer_ について読んでみてください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:66 -msgid ":file:`setup.py` serves two primary functions:" -msgstr ":file:`setup.py` はふたつの主要な機能を提供します。" +#: ../source/flow.rst:3 +msgid "The Packaging Flow" +msgstr "パッケージングの流れ" -#: ../source/guides/distributing-packages-using-setuptools.rst:68 +#: ../source/flow.rst:5 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()`` " -"function. The keyword arguments to this function are how specific details " -"of your project are defined. The most relevant arguments are explained in :" -"ref:`the section below `." +"The document aims to outline the flow involved in publishing/distributing a :" +"term:`distribution package `, usually to the `Python " +"Package Index (PyPI)`_. It is written for package publishers, who are " +"assumed to be the package author." msgstr "" -"まず、あなたのプロジェクトをさまざまな角度から設定するためのファイルです。 :" -"file:`setup.py` の主要な機能は、グローバルな ``setup()`` 関数を含んでいること" -"です。この関数にキーワード引数を渡すことで、あなたのプロジェクトの特定の細部" -"を定義することができます。適切な引数のほとんどについて :ref:`次節 ` で説明します。" +"文書は、大抵は `Python パッケージインデックス (PyPI) `_ への :term:`配布パッケージ ` の公開や配布に必" +"要な作業の流れをおおまかに描き出すことを目的としています。パッケージの作者と" +"目される、パッケージを公開する人向けに書かれました。" -#: ../source/guides/distributing-packages-using-setuptools.rst:74 +#: ../source/flow.rst:12 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``." +"While the :doc:`tutorial ` walks through the " +"process of preparing a simple package for release, it does not fully " +"enumerate what steps and files are required, and for what purpose." msgstr "" -"それは、パッケージングする上での作業項目に関連したさまざまなコマンドを走らせ" -"るためのコマンドラインインタフェイスです。使用可能なコマンドを一覧するには、 " -"``python setup.py --help-commands`` を実行してください。" +":doc:`チュートリアル ` ではシンプルなプロジェク" +"トについてリリースの準備を行うプロセスを一通り実行しますが、どのステップでど" +"のようなファイルが必要になり、その目的は何かという部分については必ずしも完全" +"に列挙はしていません。" -#: ../source/guides/distributing-packages-using-setuptools.rst:82 +#: ../source/flow.rst:16 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 `_." +"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 "" -":file:`setup.cfg` は :file:`setup.py` のコマンド群に対するオプションの既定値" -"を含む初期化ファイルです。 `PyPA サンプルプロジェクト `_ の中の `setup.cfg `_ に使" -"用例が出ています。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:89 -msgid "README.rst / README.md" -msgstr "README.rstとREADME.md" +"パッケージを公開するには、作者のソースコードからエンドユーザの Python 環境に" +"至る流れが必要とされます。これを実現するためのステップとしては:" -#: ../source/guides/distributing-packages-using-setuptools.rst:91 +#: ../source/flow.rst:19 msgid "" -"All projects should contain a readme file that covers the goal of the " -"project. The most common format is `reStructuredText `_ with an \"rst\" extension, although this is not a " -"requirement; multiple variants of `Markdown `_ are supported as well (look at ``setup()``'s :ref:" -"`long_description_content_type ` argument)." +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." msgstr "" -"すべてのプロジェクトは、プロジェクトのゴールを記したreadmeファイルを備えるべ" -"きです。一番良くあるフォーマットは拡張子が \"rst\" の `reStructuredText " -"`_ ですが、これは(訳註、必須の)要求" -"事項というわけではありません。他にも複数の種類の `マークダウン `_ フォーマットがサポートされています" -"(``setup()`` の :ref:`long_description_content_type ` 引数を見て" -"ください)。" +"パッケージを含むソースツリーを入手します。これは、典型的にはバージョン管理シ" +"ステム (VCS) からのチェックアウトのことです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:98 +#: ../source/flow.rst:22 msgid "" -"For an example, see `README.md `_ from the `PyPA sample project `_." +"Prepare a configuration file describing the package metadata (name, version " +"and so forth) and how to create the build artifacts. For most packages, this " +"will be a :file:`pyproject.toml` file, maintained manually in the source " +"tree." msgstr "" -"`PyPA sample project `_ の中の " -"`README.md `_ に例" -"が出ています。" +"パッケージのメタデータ (名前・バージョン・その他) とビルド成果物を作成するた" +"めの方法を記述した設定ファイルを用意してください。ほとんどのパッケージ向けに" +"は、これは、ソースツリー内で手動で維持管理される :file:`pyproject.toml` ファ" +"イルを準備するということになるでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:102 +#: ../source/flow.rst:27 msgid "" -"Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" -"`README.rst`, :file:`README.txt`, or :file:`README`) included in source " -"distributions by default. The built-in :ref:`distutils` library adopts this " -"behavior beginning in Python 3.7. Additionally, :ref:`setuptools` 36.4.0+ " -"will include a :file:`README.md` if found. If you are using setuptools, you " -"don't need to list your readme file in :file:`MANIFEST.in`. Otherwise, " -"include it to be explicit." +"Create build artifacts to be sent to the package distribution service " +"(usually PyPI); these will normally be a :term:`source distribution " +"(\"sdist\") ` and one or more :term:" +"`built distributions (\"wheels\") `. These are made by a " +"build tool using the configuration file from the previous step. Often there " +"is just one generic wheel for a pure Python package." 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` に明記す" -"る必要はありません。そうでないなら、明示的に書いてください。" +"パッケージ配布サービス (通常は PyPI) へ送るビルド成果物を作成してください; 普" +"通ならこれらは :term:`ソースコード配布物 (\"sdist\") ` と、ひとつまたはそれ以上の :term:`ビルド済配布物 " +"(\"wheels\") ` ということになるでしょう。これらは、前のス" +"テップで作成した設定ファイルを使ってビルドツールによって作成されます。純 " +"Python パッケージの場合には、共通の wheel がひとつだけ存在するということもし" +"ばしばあります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:111 -msgid "MANIFEST.in" -msgstr "MANIFEST.in" +#: ../source/flow.rst:35 +msgid "Upload the build artifacts to the package distribution service." +msgstr "ビルド成果物をパッケージ配布サービスへアップロードしてください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:113 +#: ../source/flow.rst:37 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`\"." +"At that point, the package is present on the package distribution service. " +"To use the package, end users must:" msgstr "" -"自動的に追加されるファイル以外のファイルをソースコード配布物に追加したい場合" -"には、 :file:`MANIFEST.in` が必要になります。 どんなファイルがデフォルトで自" -"動的に追加されるのかも含めて、 :file:`MANIFEST.in` の書き方の詳細については" -"「 :ref:`MANIFEST.in の使い方 `」を見てください。" +"その時点で、パッケージがパッケージ配布サービス上に存在することになります。そ" +"のパッケージを使うためにエンドユーザは次のことをしなければなりません:" -#: ../source/guides/distributing-packages-using-setuptools.rst:118 +#: ../source/flow.rst:40 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." +"Download one of the package's build artifacts from the package distribution " +"service." msgstr "" -"しかしながら、あなたは必ずしも :file:`MANIFEST.in` を使わなくても構いません。" -"一つの例として`PyPA サンプルプロジェクト `_ では、必要なファイルがすべて 43.0.0およびこれ以降の:ref:" -"`setuptools`に含まれているので、マニフェストファイルを削除しています。" +"そのパッケージのビルド成果物をパッケージ配布サービスからダウンロードしてくだ" +"さい。" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/flow.rst:43 msgid "" -":file:`MANIFEST.in` does not affect binary distributions such as wheels." +"Install it in their Python environment, usually in its ``site-packages`` " +"directory. This step may involve a build/compile step which, if needed, must " +"be described by the package metadata." msgstr "" -":file:`MANIFEST.in` は、wheelなどのバイナリ配布物には影響を与えません。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:126 -msgid "LICENSE.txt" -msgstr "LICENSE.txt" +"それをエンドユーザの Python 環境の通常であれば ``site-packages`` ディレクトリ" +"にインストールしてください。もしそれが必要ならパッケージのメタデータにその方" +"法が記述されていなければなりませんが、このステップにはビルド/コンパイルのス" +"テップを含むことがあります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:128 +#: ../source/flow.rst:47 msgid "" -"Every package should include a license file detailing the terms of " -"distribution. In many jurisdictions, packages without an explicit license " -"can not be legally used or distributed by anyone other than the copyright " -"holder. If you're unsure which license to choose, you can use resources such " -"as `GitHub's Choose a License `_ or consult a " -"lawyer." +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." msgstr "" -"各パッケージは、配布の条件を指定するライセンスファイルを含んでいるべきです。" -"多くの司法管轄区域(訳註、大雑把にいうと「多くの国」)では、明示的なライセンス" -"条項がないと、著作権保持者でなければ誰も適法にパッケージを使用したり配布した" -"りすることができません。どのライセンスを選択すればよいか分からない場合には、" -"`GitHubの「オープンソースライセンスを選ぶには」 `_ などのリソースを見ることも、弁護士に相談することもできます。" +"これら最後のふたつのステップは、典型的な場合には、エンドユーザが ``pip " +"install`` を走らせた時に :ref:`pip` によって実行されます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:134 -msgid "" -"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." -msgstr "" -"`PyPAサンプルプロジェクト `_ の " -"`LICENSE.txt `_ に例がでています。" +#: ../source/flow.rst:50 +msgid "The steps above are described in more detail below." +msgstr "上記のステップについては、以下にもっと詳しく記述してあります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:139 -msgid "" -msgstr "<あなたのパッケージ>" +#: ../source/flow.rst:53 +msgid "The source tree" +msgstr "ソースコードツリー" -#: ../source/guides/distributing-packages-using-setuptools.rst:141 +#: ../source/flow.rst:55 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." +"The source tree contains the package source code, usually a checkout from a " +"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 "" -"必ずそうしなければならないというわけではありませんが、あなたのプロジェクトと" -"同じか非常に近い :ref:`名前 ` の単一のプロジェクトをPythonのモ" -"ジュールやパッケージのトップレベルに配置するということが共通の慣習になってい" -"ます。" +"ソースコードツリーには、パッケージのソースコード (通常なら VCS からのチェック" +"アウト) が含まれます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:145 +#: ../source/flow.rst:60 +msgid "The configuration file" +msgstr "設定ファイル" + +#: ../source/flow.rst:62 msgid "" -"For an example, see the `sample `_ package that's included in the `PyPA sample project " -"`_." +"The configuration file depends on the tool used to create the build " +"artifacts. The standard practice is to use a :file:`pyproject.toml` file in " +"the `TOML format`_." msgstr "" -"`PyPAサンプルプロジェクト `_ に含まれ" -"る `サンプル `_ " -"パッケージに例が出ています。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:153 -msgid "setup() args" -msgstr "setup() の引数" +"ビルド成果物を作成するのに用いるツールによって設定ファイルは変わります。" +"`TOML フォーマット `_ で書かれた `pyproject.toml` ファイルを使う" +"のが標準的な慣習です。" -#: ../source/guides/distributing-packages-using-setuptools.rst:155 +#: ../source/flow.rst:68 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." +"At a minimum, the :file:`pyproject.toml` file needs a ``[build-system]`` " +"table specifying your build tool. There are many build tools available, " +"including but not limited to :ref:`flit`, :ref:`hatch`, :ref:`pdm`, :ref:" +"`poetry`, :ref:`setuptools`, `trampolim`_, and `whey`_. Each tool's " +"documentation will show what to put in the ``[build-system]`` table." msgstr "" -"上述の通り、:file:`setup.py` の第一の機能は、グローバルスコープの " -"``setup()`` 関数を含むことです。この関数に与えるキーワード引数は、あなたのプ" -"ロジェクトの特定の細部がどのように定義されているかを示すものです。" +":file:`pyproject.toml` ファイルには、少なくとも、採用したビルドツールを指定す" +"る ``[build-system]`` テーブルがなければなりません。ビルドツールとして使える" +"ものには、 :ref:`flit` ・ :ref:`hatch` ・ :ref:`pdm` ・ :ref:`poetry` ・ :" +"ref:`setuptools` ・ `trample`_ ・ `whey`_ を含めて他にもさまざまなものがあり" +"ます。それぞれのツールの説明文書には、 ``[build-system]`` に何を書けば良いか" +"が示されていることでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:159 +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "例えば、 :ref:`hatch` を使う場合のテーブルは次のようになります:" + +#: ../source/flow.rst:85 msgid "" -"Some are temporarily explained below until their information is moved " -"elsewhere. The full list can be found :doc:`in the setuptools documentation " -"`." +"With such a table in the :file:`pyproject.toml` file, a \":term:`frontend " +"`\" tool like :ref:`build` can run your chosen build tool's " +"\":term:`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." msgstr "" -"いくつかについては、情報がどこか他の場所に移されるまでの一時的な説明が以下に" -"あります。すべてを列挙したものは :doc:`setuptools の説明文書 ` で見つかるでしょう。" +":file:`pyproject.toml` ファイルの中のそのようなテーブルを用いることで、 :ref:" +"`build` のような \":term:`フロントエンド `\" のツールが、ビル" +"ド成果物を作成するためにあなたが選んだビルドツールの \":term:`バックエンド " +"`\" を実行することができます。あなたが選んだビルドツールが独自" +"のフロントエンドを提供しても構いません。 :ref:`pip` のようなインストールツー" +"ルもまた、ソースコード配布物からインストールする時にあなたのビルドツールバッ" +"クエンドを走らせることで、フロントエンドとして振る舞うことができます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:163 +#: ../source/flow.rst:94 msgid "" -"Most of the snippets given are taken from the `setup.py `_ " -"contained in the `PyPA sample project `_." +"The particular build tool you choose dictates what additional information is " +"required in the :file:`pyproject.toml` file. For example, you might specify:" msgstr "" -"ほとんどのソースコード断片(スニペット)は、`PyPA サンプルプロジェクト " -"`_ の中の `setup.py `_ から取られたものです。" +"あなたが選択した特定のビルドツールに応じてどんな追加の情報を :file:" +"`pyproject.toml` ファイルに記述しなければならないかがきまります。例えば、以下" +"のように指定することができます:" -#: ../source/guides/distributing-packages-using-setuptools.rst:170 +#: ../source/flow.rst:97 msgid "" -"See :ref:`Choosing a versioning scheme` for more information on ways to use " -"versions to convey compatibility information to your users." +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," msgstr "" -"あなたのユーザへ互換性情報を伝える方法としてバージョン番号を使うやり方につい" -"ては、 :ref:`バージョンをつける規則を選択するには ` をご覧ください。" +":doc:`コアとなるメタデータ ` (名前・バージョ" +"ン・作者・その他) を含む ``[project]``、" -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "``packages``" -msgstr "``packages``" +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "ツール特有の設定オプションを含んだ ``[tool]`` テーブル。" -#: ../source/guides/distributing-packages-using-setuptools.rst:183 +#: ../source/flow.rst:103 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." +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -"``packages`` には、あなたのプロジェクトにある :term:`パッケージ ` を子パッケージや孫パッケージなども含めてすべて列挙してください。" -"パッケージは手動で列挙することもできますが、 ``setuptools.find_packages()`` " -"を使えば自動で列挙することができます。 ``include`` キーワード引数を使うと、こ" -"こに与えられた特定のパッケージだけを探索することができます。 ``exclude`` キー" -"ワード引数を使うと、公開したりインストールしたりする意図のないパッケージを除" -"外することができます。" +"``pyproject.toml`` の設定に関する完全なガイド文書としては、 :ref:`pyproject." +"toml ガイド文書 ` を参照してください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:192 -msgid "``py_modules``" -msgstr "``py_modules``" +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "ビルド成果物" -#: ../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." +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" msgstr "" -"あなたのプロジェクトに、プロジェクトの一部ではない単一ファイルのPythonモ" -"ジュールがあるなら、 :ref:`setuptools` に知らせるために、そのようなモジュール" -"の(拡張子``.py``を削除した)名前を ``py_modules`` に列挙してください。" +"`ソースコード配布物 (またはsdist) `" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 -msgid "``install_requires``" +#: ../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 " +"may also include tests and documentation. These are useful for end users " +"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/guides/distributing-packages-using-setuptools.rst:210 +#: ../source/flow.rst:119 ../source/flow.rst:143 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." +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" msgstr "" -"``install_requires`` は、プロジェクトが動作するために最低限必要な依存関係を指" -"定するのに使われます。プロジェクトが :ref:`pip` でインストールされる場合に" -"は、この指定を見て依存関係(訳註、にある他パッケージ)をインストールするために" -"用いられます。" +":ref:`build` パッケージは、次のうちのいずれかを生成するためにあなたの選んだビ" +"ルドツールをどのように呼び出すのかを知っています:" -#: ../source/guides/distributing-packages-using-setuptools.rst:214 +#: ../source/flow.rst:126 msgid "" -"For more on using \"install_requires\" see :ref:`install_requires vs " -"Requirements files`." +"Or, your build tool may provide its own interface for creating an sdist." msgstr "" -"さらなる ``install_requires`` の使い方については :ref:`install_requires対" -"Requirementsファイル ` を参照してくだ" -"さい。" +"あるいは、あなたの選んだツールが、 sdist を生成するためのツール独自のインタ" +"フェースを提供しているかもしれません。" -#: ../source/guides/distributing-packages-using-setuptools.rst:221 -msgid "``package_data``" -msgstr "``package_data``" +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "ビルド済み配布物 (wheels)" -#: ../source/guides/distributing-packages-using-setuptools.rst:230 +#: ../source/flow.rst:132 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\"." +"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 "" -"追加のファイルを :term:`パッケージ ` にインストールする必要が" -"ある、というのはよくあることです。このようなファイルは、しばしば、そのパッ" -"ケージの実装に深く関係していたり、パッケージを利用するプログラマの利益になる" -"ような説明を含んだテキストファイルであったりします。このようなファイルは" -"「パッケージデータ」と呼ばれます。" +"ビルド済配布物は、エンドユーザの Python 環境に必要とされるファイル群だけを含" +"んでいます。インストールの際にコンパイル工程は不要で、 wheel ファイルの内容" +"を ``site-packages`` ディレクトリに単純に展開することができます。これによって" +"インストールが素早く行われ、エンドユーザにとってより便利であると言えるでしょ" +"う。" -#: ../source/guides/distributing-packages-using-setuptools.rst:235 +#: ../source/flow.rst:137 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." +"A pure Python package typically needs only one \"generic\" wheel. A package " +"with compiled binary extensions needs a wheel for each supported combination " +"of Python interpreter, operating system, and CPU architecture that it " +"supports. If a suitable wheel file is not available, tools like :ref:`pip` " +"will fall back to installing the source distribution." msgstr "" -"この引数に渡す値は、パッケージ名から、そのパッケージ内にコピーされるべきファ" -"イルの相対パス名を列挙したもののマッピングになっていなければなりません。パス" -"名はパッケージを含むディレクトリからの相対パスとして解釈されます。" +"純 Python パッケージでは、典型的には、ひとつの \"万能型\" の wheel さえあれば" +"十分です。コンパイル済みのバイナリ拡張を伴うパッケージでは、そのパッケージが" +"サポートする Python インタプリタ・オペレーティングシステム・ CPU アーキテク" +"チャの組み合わせのそれぞれについて wheel ファイルが必要になります。適切な " +"wheel ファイルが利用できない場合には、 :ref:`pip` のようなツールはソースコー" +"ド配布物からのインストールにフォールバックします。" -#: ../source/guides/distributing-packages-using-setuptools.rst:239 -msgid "" -"For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -"詳しくは、 :std:doc:`setuptools説明文書 ` の中の :std:doc:`" -"データファイルを追加するには <1setuptools:userguide/datafiles>` を見てくださ" -"い。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:247 -msgid "``data_files``" -msgstr "``data_files``" +"あるいは、あなたの選んだビルドツールが wheel を生成するための独自のインタ" +"フェースを提供しているかもしれません。" -#: ../source/guides/distributing-packages-using-setuptools.rst:253 +#: ../source/flow.rst:154 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:" -"`packages `. The ``data_files`` directive allows you to do " -"that. It is mostly useful if you need to install files which are used by " -"other programs, which may be unaware of Python packages." +"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:`パッケージデータ ` を設定すればほとんどの需要に応えられま" -"すが、あなたの :term:`パッケージ ` の *外側* にデータファイル" -"を置きたいこともあるでしょう。 ``data_files`` ディレクティブでそれができま" -"す。大抵は、Pythonのパッケージを認識しないような他のプログラムから利用する" -"ファイルをインストールする必要がある時に、これが役に立つでしょう。" +":ref:`build` のデフォルトの動作は、カレントディレクトリにあるソースコードか" +"ら sdist と wheel の両方を作成することです; 上記の例は意図的に特定の動作をさ" +"せています。" -#: ../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 " -"relative path (although this may change in the future, see `wheel Issue #92 " -"`_), and it is interpreted relative " -"to the installation prefix (Python’s ``sys.prefix`` for a default " -"installation; ``site.USER_BASE`` for a user installation). Each file name in " -"``files`` is interpreted relative to the :file:`setup.py` script at the top " -"of the project source distribution." -msgstr "" -"設定値の中の ``(ディレクトリ, ファイル)`` の組は、それぞれインストール先の" -"ディレクトリとそこにインストールされるべきファイル(群)を指定しています。 ``" -"ディレクトリ `` は相対パスでなければならず (これは将来変更されるか" -"もしれません。 `wheel Issue #92 `_ " -"を見てください)、インストール先プレフィクス(デフォルトではPythonの ``sys." -"prefix``、ないし、ユーザインストールでは ``site.USER_BASE`` )に対する相対パス" -"として解釈されます。 ``files`` 内のファイル名は、プロジェクトのソースコード配" -"布物の最上位にある :file:`setup.py` スクリプトに対する相対パスとして解釈され" -"ます。" +#: ../source/flow.rst:159 +msgid "Upload to the package distribution service" +msgstr "パッケージ配布サービスへアップロードする" -#: ../source/guides/distributing-packages-using-setuptools.rst:269 +#: ../source/flow.rst:161 msgid "" -"For more information see the distutils section on :ref:`Installing " -"Additional Files `." +"The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " +"using a command like:" msgstr "" -"さらに詳しくは、 :ref:`追加的なファイルをインストールするには ` の中のdistutilsの節を見てください。" +"ツールの :ref:`twine` の以下のようなコマンドを使って、配布のためにビルド成果" +"物を PyPI へアップロードすることができます:" -#: ../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." +#: ../source/flow.rst:168 +msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -"パッケージをeggとしてインストールする時には、 ``data_files`` はサポートされて" -"いません。だから、もしあなたのプロジェクトで :ref:`setuptools` を使っているな" -"らば ``pip`` でインストールしなければなりません。あるいは、 ``--old-and-" -"unmanageable`` オプション付きの ``python setup.py`` を使わなければなりませ" -"ん。" +"あるいは、あなたの選んだビルドツールにアップロードのための独自のインタフェー" +"スが備わっているかもしれません。" -#: ../source/guides/distributing-packages-using-setuptools.rst:281 -#: ../source/specifications/pyproject-toml.rst:146 -msgid "``scripts``" +#: ../source/flow.rst:171 +msgid "Download and install" +msgstr "ダウンロードとインストール" + +#: ../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/guides/distributing-packages-using-setuptools.rst:283 +#: ../source/flow.rst:181 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)." +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" +"ref:`pdm`." msgstr "" -"``setup()`` はあらかじめ作成されたスクリプトをインストールするために :ref:" -"`scripts ` キーワードをサポートして" -"いますが、異機種間の互換性を取るためのアプローチとして推奨されるのは :ref:" -"`console_scripts` エントリーポイント(後述)を使うことです。" +"エンドユーザは、 :ref:`pipenv` ・ :ref:`poetry` ・ :ref:`ppm` のような他の" +"ツールを使うことも可能です。" -#: ../source/guides/distributing-packages-using-setuptools.rst:291 -msgid "Choosing a versioning scheme" -msgstr "バージョン体系を選択する" +#: ../source/glossary.rst:3 +msgid "Glossary" +msgstr "用語集" -#: ../source/guides/distributing-packages-using-setuptools.rst:293 +#: ../source/glossary.rst:8 +msgid "Binary Distribution" +msgstr "バイナリ配布物" + +#: ../source/glossary.rst:11 msgid "" -"See :ref:`versioning` for information on common version schemes and how to " -"choose between them." +"A specific kind of :term:`Built Distribution` that contains compiled " +"extensions." msgstr "" -"よくあるバージョンを指定する枠組みにどんなものがあるかや、その中からひとつの" -"枠組みを選択する方法については、 :ref:`バージョニング ` を見てく" -"ださい。" +"`ビルド済配布物 `の特定の種類で、コンパイル済みの拡張部分" +"を含むもの。" -#: ../source/guides/distributing-packages-using-setuptools.rst:298 -msgid "Working in \"development mode\"" -msgstr "開発モードで作業する" +#: ../source/glossary.rst:14 +msgid "Build Backend" +msgstr "ビルドバックエンド" -#: ../source/guides/distributing-packages-using-setuptools.rst:300 +#: ../source/glossary.rst:17 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 " -"without reinstallation: changes to Python source files in projects installed " -"as editable will be reflected the next time an interpreter process is " -"started." +"A library that takes a source tree or :term:`source distribution ` and builds a source distribution or :term:" +"`wheel ` from it. The build is delegated to the backend by a :term:" +"`frontend `. All backends offer a standardized interface." msgstr "" -"あなたがまだ作業している途中なら、プロジェクトを「編集可能」または「開発」" -"モードでインストールすることができます。編集可能な状態でインストールされる" -"と、再インストールしなくてもプロジェクトをその場で編集することができます: 編" -"集可能状態でインストールされたプロジェクトのPythonソースコードに変更を加える" -"と、次にインタープリターのプロセスが開始された時に反映されます。" +"ソースコードツリーや :term:`ソースコード配布物 ` を受け取って、そこからソースコード配布物や :term:`wheel " +"` をビルドするライブラリ。ビルド自体は :term:`フロントエンド ` によってバックエンドに任されます。すべてのバックエンドは標準化され" +"たインターフェースを提供します。" -#: ../source/guides/distributing-packages-using-setuptools.rst:306 +#: ../source/glossary.rst:24 msgid "" -"To install a Python package in \"editable\"/\"development\" mode Change " -"directory to the root of the project directory and run:" +"Examples of build backends are :ref:`flit's flit-core `, :ref:`hatch's " +"hatchling `, :ref:`maturin`, :ref:`meson-python`, :ref:`scikit-build-" +"core`, and :ref:`setuptools`." msgstr "" -"Pythonのパッケージを「編集可能」/「開発」モードでインストールするには、そのプ" -"ロジェクトのルートディレクトリへ移動して、次のコマンドを走らせてください:" +"ビルドバックエンドの例としては、 :ref:`flit の flit-core ` 、 :ref:" +"`hatchのhatchling ` 、 :ref:`maturin` 、 :ref:`meson-python` 、 :ref:" +"`scikit-build-core` 、 :ref:`setuptools` があります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:314 +#: ../source/glossary.rst:32 +msgid "Build Frontend" +msgstr "ビルドフロントエンド" + +#: ../source/glossary.rst:35 msgid "" -"The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " -"refers to the current working directory, so together, it means to install " -"the current directory (i.e. your project) in editable mode. This will also " -"install any dependencies declared with ``install_requires`` and any scripts " -"declared with ``console_scripts``. Dependencies will be installed in the " -"usual, non-editable mode." +"A tool that users might run that takes arbitrary source trees or :term:" +"`source distributions ` and builds " +"source distributions or :term:`wheels ` from them. The actual " +"building is delegated to each source tree's :term:`build backend `." msgstr "" -"pip のコマンドラインオプションの ``-e`` は ``--editable`` の省略形で、 ``.`` " -"は現在作業をしているディレクトリのことですので、まとめると「現在のディレクト" -"リ(つまりあなたのプロジェクト)に編集可能モードでインストールせよ」ということ" -"になります。また、このコマンドによって ``install_requires`` に宣言された依存" -"先のパッケージや ``console_scripts`` に書かれたスクリプトもインストールされま" -"す。" +"任意のソースコードツリーまたは :term:`ソースコード配布物 ` を入力として、それらからソースコード配布物また" +"は :term:`wheels ` をビルドするためにユーザが走らせるであろうツール。" +"実際のビルド作業は、それぞれのソースコードツリーの :term:`ビルドバックエンド " +"` に委任されます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:321 -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::" +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." msgstr "" -"依存先のプロジェクトも同様に編集可能モードでインストールしたい時があるかもし" -"れません。例えば、あなたのプロジェクトが \"foo\" と \"bar\" というパッケージ" -"を要求していて、 \"bar\" についてはVCS (バージョンコントロールシステム) から" -"編集可能モードでインストールしたい場合には、requirements ファイルを次のように" -"構成すれば良いでしょう::" +"ビルドフロントエンドの例としては、 :ref:`pip` や :ref:`build` があります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:329 +#: ../source/glossary.rst:44 +msgid "Built Distribution" +msgstr "ビルド済配布物" + +#: ../source/glossary.rst:47 +#, fuzzy 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." +"A :term:`Distribution ` format containing files and " +"metadata that only need to be moved to the correct location on the target " +"system, to be installed. :term:`Wheel` is such a format, whereas :term:" +"`Source Distribution ` is not, in that " +"it requires a build step before it can be installed. This format does not " +"imply that Python files have to be precompiled (:term:`Wheel` intentionally " +"does not include compiled Python files). See :ref:`package-formats` for more " +"information." msgstr "" -"最初の行ではあなたのプロジェクトとその依存先をインストールするように指示して" -"います。２行目で、 \"bar\" についてPyPIではなくVCSから充当するようにと依存関" -"係を上書きしています。" +":term:`配布物 `とは、ターゲットとなるシステムの適切な位" +"置に移動することでインストールされるファイルやメタデータを内包したフォーマッ" +"トです。:term:`Wheel`はそのようなフォーマットですが、他方で、distutilの :" +"term:`ソースコード配布物 `, :term:`modules `, and other resource files that are used " +"to distribute a :term:`Release`. The archive file is what an end-user will " +"download from the internet and install." msgstr "" -"そうではなくて、 \"bar\" をローカルディレクトリから編集可能モードでインストー" -"ルしたい場合には、 requirements ファイルの先頭にローカルのディレクトリパスを" -"置いて次のようになるでしょう::" +":term:`モジュール `すなわちPythonの :term:`パッケージ `や、ある :term:`Release`を配布するために使われるその他のリソースファ" +"イルを内部に含むバージョン付きアーカイブファイル。アーカイブファイルはエンド" +"ユーザがインターネットからダウンロードしてインストールするものです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:338 +#: ../source/glossary.rst:64 msgid "" -"Otherwise, the dependency will be fulfilled from PyPI, due to the " -"installation order of the requirements file. For more on requirements " -"files, see the :ref:`Requirements File ` section in " -"the pip docs. For more on VCS installs, see the :ref:`VCS Support ` section of the pip docs." +"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\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -"さもなければ requirements ファイルに書かれた順にインストールされてしまうの" -"で、依存先のパッケージが PyPI から充当されてしまいます。 requirements ファイ" -"ルについてさらに詳しく知りたい場合は、 pipの解説文書の :ref:`Requirements " -"ファイル ` の節を見てください。VCSからのインストール" -"については、同書の :ref:`VCSサポート ` の節を見てください。" +"配布パッケージは単語ひとつで「パッケージ」や「配布物」と呼ばれることもしばし" +"ばですが、本ガイドでは、 :term:`インポートパッケージ `(これも" +"通常は単に「パッケージ」と呼ばれます)や他の種類の配布物(例えばLinuxディストリ" +"ビューションやPython言語の配布物)でよく単語ひとつの「配布物」と呼ばれるものと" +"の混同を避けるために明確に述べる必要がある場合には、長い方の用語を用いること" +"があります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:342 +#: ../source/glossary.rst:72 +msgid "Egg" +msgstr "卵" + +#: ../source/glossary.rst:75 +#, fuzzy msgid "" -"Lastly, if you don't want to install any dependencies at all, you can run:" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." msgstr "" -"最後に、もし依存先パッケージは何もインストールしたくないのであれば、このよう" -"にします:" +":term:`Egg` フォーマットを代替することを意図して :pep:`427` で導入された :" +"term:`ビルド済配布物`。現在、:ref:`pip`はWheelをサポートしている。" -#: ../source/guides/distributing-packages-using-setuptools.rst:349 +#: ../source/glossary.rst:78 +msgid "Extension Module" +msgstr "拡張モジュール" + +#: ../source/glossary.rst:81 msgid "" -"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +"A :term:`Module` written in the low-level language of the Python " +"implementation: C/C++ for Python, Java for Jython. Typically contained in a " +"single dynamically loadable pre-compiled file, e.g. a shared object (.so) " +"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 "" -"さらに詳しいことを知りたい場合は、 :ref:`setuptools` 文書の :doc:`開発モード " -"` の 節を見てください。" +":term:`モジュール `とは、Pythonの実装のうちの低レベル言語で書かれた部" +"分で、C/C++で書かれたCythonやJavaで書かれたJythonが該当する。典型的には動的に" +"ロードできるコンパイル済みのファイルをひとつ含んでいて、Unix上では共有オブ" +"ジェクトファイル(.so)、Windows上ではDLL(拡張子.pydを与えられる)のPython拡張、" +"Jython拡張ではJavaのクラスファイルの形を取る。" -#: ../source/guides/distributing-packages-using-setuptools.rst:356 -msgid "Packaging your project" -msgstr "プロジェクトをパッケージングする" +#: ../source/glossary.rst:88 +msgid "Known Good Set (KGS)" +msgstr "既知の良好なセット" -#: ../source/guides/distributing-packages-using-setuptools.rst:358 +#: ../source/glossary.rst:91 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." +"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 " +"specific set of packages is declared a known good set. This term is commonly " +"used by frameworks and toolkits which are comprised of multiple individual " +"distributions." msgstr "" -"あなたのプロジェクトを :term:`PyPI ` のような :" -"term:`パッケージインデックス ` からインストールできるようにす" -"るには、 :term:`配布物 ` (:term:`パッケージ " -"`の名前でも知られる) を作成しなければならないでしょう。" +"(KGSとは)相互に互換性のある特定のバージョンの配布物の集合。典型的には、テスト" +"スイートで全てのテストに合格して実行できるようなパッケージの特定の組み合わせ" +"が既知の良好なセット(KGS)であると宣言されます。この用語は、個々の配布物を複数" +"組み合わせて構成されるフレームワークやツールキットで共通して用いられます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:363 +#: ../source/glossary.rst:97 +msgid "Import Package" +msgstr "インポートパッケージ" + +#: ../source/glossary.rst:100 msgid "" -"Before you can build wheels and sdists for your project, you'll need to " -"install the ``build`` package:" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" +"直接に、あるいは何段階になっても良いが、他のパッケージを組み込んで使うような" +"Pythonモジュール。" + +#: ../source/glossary.rst:103 +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\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -"あなたのプロジェクトでwheelsやsdistsをビルドする前に、 ``build`` パッケージを" -"インストールする必要があります。" +"インポートパッケージは、より普通には「パッケージ」という１単語の用語で呼ばれ" +"ますが、本ガイドでは、同様に単に「パッケージ」と呼ばれることが普通である :" +"term:`配布物パッケージ `との混同を避けるために必要な場" +"合には、長い方の用語を用いることにします。" -#: ../source/guides/distributing-packages-using-setuptools.rst:380 -msgid "Source distributions" -msgstr "ソースコード配布物" +#: ../source/glossary.rst:108 +msgid "Module" +msgstr "モジュール" -#: ../source/guides/distributing-packages-using-setuptools.rst:382 +#: ../source/glossary.rst:111 msgid "" -"Minimally, you should create a :term:`Source Distribution `:" +"The basic unit of code reusability in Python, existing in one of two types: :" +"term:`Pure Module`, or :term:`Extension Module`." msgstr "" -"少なくとも、 :term:`ソースコード配布物 ` " -"を作成するべきです:" +"Pythonにおけるソースコード再利用の基本的な単位で、 :term:`Pure Module`か :" +"term:`Extension Module`の二つのタイプのうちのいずれか。" -#: ../source/guides/distributing-packages-using-setuptools.rst:398 +#: ../source/glossary.rst:114 +msgid "Package Index" +msgstr "パッケージインデックス" + +#: ../source/glossary.rst:117 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 " -"the distribution is pure Python (i.e. contains no extensions), it still " -"involves a build step to build out the installation metadata from :file:" -"`setup.py` and/or :file:`setup.cfg`." +"A repository of distributions with a web interface to automate :term:" +"`package ` discovery and consumption." msgstr "" -"ソースコード配布物はビルドされていない (すなわち、 :term:`ビルド済み配布物 " -"` ではない) ので、pip でインストールする際にビルドする段" -"階が必要になります。配布物が純Python (つまり (訳注、多言語で書かれた) 拡張を" -"含まない) であったとしても、 :file:`setup.py` や :file:`setup.cfg` からインス" -"トール用メタデータを取り出してビルドする段階を必要とするのです。" +":term:`パッケージ `の発見・消費(訳註、意訳になるが検" +"索・ダウンロードが適切か)を自動化するwebインターフェイスを伴った配布物のリポ" +"ジトリ。" -#: ../source/guides/distributing-packages-using-setuptools.rst:406 -msgid "Wheels" -msgstr "Wheels" +#: ../source/glossary.rst:120 +msgid "Per Project Index" +msgstr "プロジェクト単位の索引" -#: ../source/guides/distributing-packages-using-setuptools.rst:408 +#: ../source/glossary.rst:123 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 " -"through the \"build\" process. Installing wheels is substantially faster for " -"the end user than installing from a source distribution." +"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 "" -"あなたのプロジェクトでは、wheelも作成するべきです。wheel は、インストールする" -"のにビルド処理を行う必要がない :term:`ビルド済み配布物 ` " -"です。wheelを使えば、ソースコード配布物からのインストールに比べてエンドユーザ" -"にとって相当素早くインストールすることができます。" +"ある :term:`プロジェクト `が嗜好するか要求する依存関係を解決するため" +"に、:term:`プロジェクト `の単位で示された仲間内または非公式の :term:" +"`パッケージ索引 `。" -#: ../source/guides/distributing-packages-using-setuptools.rst:413 +#: ../source/glossary.rst:127 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "プロジェクト" + +#: ../source/glossary.rst:130 msgid "" -"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " -"Wheel\" (see section below) `." +"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 "" -"あなたのプロジェクトが純Pythonなら、きっとあなたは:ref:`\"純Pythonの" -"Wheel\" (後述) `を作成することになるでしょう。" +"ライブラリ、フレームワーク、スクリプト、プラグイン、アプリケーション、ないし" +"一連のデータもしくはその他のリソース、または、これらの組み合わせで :term:`配" +"布物 `として意図的にパッケージされたもの。" -#: ../source/guides/distributing-packages-using-setuptools.rst:416 +#: ../source/glossary.rst:134 msgid "" -"If your project contains compiled extensions, then you'll be creating what's " -"called a :ref:`*Platform Wheel* (see section below) `." +"Since most projects create :term:`Distributions ` " +"using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" +"`setuptools`, another practical way to define projects currently is " +"something that contains a :term:`pyproject.toml`, :term:`setup.py`, or :term:" +"`setup.cfg` file at the root of the project source directory." msgstr "" -"もしあなたのプロジェクトにコンパイル済の拡張が含まれているなら、 :ref:`*プ" -"ラットフォーム Wheel* (後述) ` を作成することになるでしょ" -"う。" +"ほとんどのプロジェクトで :pep:`518` ``build-system``として :ref:`distutils`" +"か :ref:`setuptools`を用いて :term:`配布物 `を作成しま" +"すので、現時点でプロジェクトを定義するもうひとつの実践的な方法は、プロジェク" +"トのソースコードの一番上のディレクトリに :term:`pyproject.toml`や :term:" +"`setup.py`または :term:`setup.cfg`のファイルを含む何ものかというものです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:419 +#: ../source/glossary.rst:140 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:" +"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 2をさぽーとしていて、かつ、C言語拡張を含むので" -"あれば、次のものをあなたの :file:`setup.cfg` ファイルに追加して *ユニバーサ" -"ル Wheel* と呼ばれるものを作成するべきです:" +"Pythonにおけるプロジェクトは、 :term:`PyPI `に登" +"録される一意の名前を持っていなければなりません。そして、プロジェクトはそれぞ" +"れひとつまたはより多くの :term:`リリース `を含んでいて、各リリースは" +"ひとつまたはより多くの :term:`配布物 `を内包していま" +"す。" -#: ../source/guides/distributing-packages-using-setuptools.rst:428 +#: ../source/glossary.rst:145 msgid "" -"Only use this setting if your project does not have any C extensions *and* " -"supports Python 2 and 3." +"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 "" -"あなたのプロジェクトにC言語拡張がなく、かつ、Python 2 および3をサポートしてい" -"る場合に限って、この設定を使ってください。" +"そのプロジェクトを稼働させるためにインポートされるパッケージの名前に因んでプ" +"ロジェクトに名前をつけるのが普通であるという強い慣習があることを覚えておいて" +"ください。しかしながら、常にそうしなければならないわけではありません。「なん" +"とか」というプロジェクトから配布物をインストールしていながらも、「かんとか」" +"(訳註、「なんとか」とは無関係の別の名前の例)という名前でのみインポート可能な" +"パッケージを提供することは可能です。" -#: ../source/guides/distributing-packages-using-setuptools.rst:435 -msgid "Pure Python Wheels" -msgstr "純Python Wheels" +#: ../source/glossary.rst:151 +msgid "Pure Module" +msgstr "純粋なモジュール" -#: ../source/guides/distributing-packages-using-setuptools.rst:437 +#: ../source/glossary.rst:154 msgid "" -"*Pure Python Wheels* contain no compiled extensions, and therefore only " -"require a single Python wheel." +"A :term:`Module` written in Python and contained in a single ``.py`` file " +"(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -"*純Python Wheels* は、コンパイル済拡張を含んでおらず、従って単独のPython " -"wheelを要求するだけです。" +"Pythonで書かれていて単一の``.py``ファイル(とおそらくは対応する``.pyc``ファイ" +"ルや``.pyo``ファイル)に収められた :term:`モジュール `。" -#: ../source/guides/distributing-packages-using-setuptools.rst:440 -#: ../source/guides/distributing-packages-using-setuptools.rst:469 -msgid "To build the wheel:" -msgstr "wheelをビルドするには:" +#: ../source/glossary.rst:157 +msgid "Python Packaging Authority (PyPA)" +msgstr "Pythonパッケージングオーソリティ(PyPA)" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/glossary.rst:160 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`." +"PyPA is a working group that maintains many of the relevant projects in " +"Python packaging. They maintain a site at :doc:`pypa.io `, host " +"projects on `GitHub `_ and `Bitbucket `_, and discuss issues on the `distutils-sig mailing list " +"`_ and " +"`the Python Discourse forum `__." msgstr "" -"``wheel`` パッケージは、ソースコードが純Pythonであることを検出して、Python 3 " -"へのインストールであればどこでも使えるのでそのように名付けられたwheelをビルド" -"します。wheelファイルの名称について詳しいことは :pep:`425` を見てください。" +"PyPAは、Pythonのパッケージングに関係する多くのプロジェクトを維持管理する作業" +"グループです。その活動の一環として :doc:`papa.io ` を維持管理して" +"おり、 `GitHub `_ と `Bitbucket `_ に関連プロジェクトを置くとともに、 `distutils-sig メーリングリス" +"ト `_ と " +"`Python談話フォーラム `__ で議論を進" +"めています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:458 +#: ../source/glossary.rst:169 +msgid "Python Package Index (PyPI)" +msgstr "Pythonパッケージインデックス (PyPI)" + +#: ../source/glossary.rst:172 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." +"`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 "" -"``--wheel`` か ``--sdist`` を付けずに ``build`` を実行すると、両方のファイル" -"が作成されます; 複数のwheelファイルにしたくないときにはこれが便利です。" +"`PyPI `_ は、Pythonコミュニティにとってデフォルトの :term:" +"`Package Index`です。ここから配布物を取り出し、また、配布するためにすべての" +"Python開発者に開かれています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:464 -msgid "Platform Wheels" -msgstr "プラットフォームWheels" +#: ../source/glossary.rst:175 +msgid "pypi.org" +msgstr "pypi.org" -#: ../source/guides/distributing-packages-using-setuptools.rst:466 +#: ../source/glossary.rst:178 msgid "" -"*Platform Wheels* are wheels that are specific to a certain platform like " -"Linux, macOS, or Windows, usually due to containing compiled extensions." +"`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 "" -"*プラットフォームWheels* は、LinuxやmacOSあるいはWindowsのような特定のプラッ" -"トフォーム向けのwheelで、大抵の場合は(訳注、特定のプラットフォーム向けにコン" -"パイルされた)コンパイル済み拡張を含むためです。" +"`pypi.org `_ は、 :term:`Python パッケージインデックス" +"(PyPI)` のためのドメイン名です。2017年にそれまでのドメイン名である ``pypi." +"python.org`` を置き換えました。 :ref:`warehouse`を使っています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/glossary.rst:182 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:185 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`." +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -"``wheel`` パッケージは、ソースコードが純Pythonで書かれていないと判断すると、" -"ビルドされたプラットフォーム上でのみ利用可能であるように命名されたwheelを作成" -"します。wheelファイルの命名規則については、 :pep:`425` を見てください。" +"ツール不可知論者の :term:`プロジェクト ` 仕様を示すファイル。 :pep:" +"`518` で定義。" -#: ../source/guides/distributing-packages-using-setuptools.rst:490 +#: ../source/glossary.rst:187 +msgid "Release" +msgstr "リリース" + +#: ../source/glossary.rst:190 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`." +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." msgstr "" -"現在、 :term:`PyPI <` は、Windows向けとmacOS向" -"け、そして複数のLinuxディストリビューションに対応した ``manylinux*`` のABI向" -"けのプラットフォームWheelsをアップロードすることに対応しています。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:498 -msgid "Uploading your Project to PyPI" -msgstr "プロジェクトをPyPIにアップロードする" +"ある特定の時点における :term:`プロジェクト `のスナップショットで、" +"バージョン識別子付きのもの。" -#: ../source/guides/distributing-packages-using-setuptools.rst:500 +#: ../source/glossary.rst:193 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." +"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 "" -"配布物を作成するコマンドを走らせると、あなたのプロジェクトのルートディレクト" -"リに ``dist/`` という新しいディレクトリが作成されます。ここに配布物のファイル" -"(群)が置かれます。" +"リリースを作成することは、複数の :term:`配布物 ` を公開" +"することを伴います。例えば、あるプロジェクトのバージョン1.0がリリースされたな" +"らば、ソースコード配布物とWindowsインストーラ付配布物の両方が利用可能となって" +"いるという具合です。" -#: ../source/guides/distributing-packages-using-setuptools.rst:504 +#: ../source/glossary.rst:198 +msgid "Requirement" +msgstr "要求事項" + +#: ../source/glossary.rst:201 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 " -"or the configuration in your :file:`setup.py` file, you will need to rebuild " -"these files again before you can distribute the changes to PyPI." +"A specification for a :term:`package ` to be " +"installed. :ref:`pip`, the :term:`PYPA ` " +"recommended installer, allows various forms of specification that can all be " +"considered a \"requirement\". For more information, see the :ref:`pip:pip " +"install` reference." msgstr "" -"これらのファイルは、配布物作成のコマンドを走らせたときにだけ作成されます。と" -"いうことは、プロジェクトのソースコードや :file:`setup.py` の中の設定を変更し" -"たときにはいつでも、PyPIへ送る前に配布物のファイルを再作成する必要があるとい" -"うことです。" +"インストールされる :term:`パッケージ ` の仕様。 :term:" +"`PYPA ` が推奨するインストーラである :ref:" +"`pip` では、「要求事項」とも解釈できる仕様を様々な様式で書くことを許容してい" +"ます。詳細については、 :ref:`pip:pip install` の項を参照してください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:509 +#: ../source/glossary.rst:207 +msgid "Requirement Specifier" +msgstr "要求事項識別子" + +#: ../source/glossary.rst:210 msgid "" -"Before releasing on main PyPI repo, you might prefer training with the `PyPI " -"test site `_ which is cleaned on a semi regular " -"basis. See :ref:`using-test-pypi` on how to setup your configuration in " -"order to use it." +"A format used by :ref:`pip` to install packages from a :term:`Package " +"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 "" -"PyPIの主リポジトリでリリースをする前に、半定期的に消去される `PyPI 試験サイ" -"ト `_ で練習する方が良いかもしれません。どのように設" -"定すれば試験サイトを使えるかについては、 :ref:`using-test-pypi` を見てくださ" -"い。" +":term:`パッケージインデックス `からパッケージをインストールす" +"るために :ref:`pip` で用いられる様式。この様式の EBNF 文法構造については、 :" +"ref:`依存関係指定子 ` を見てください。例えば、 " +"\"foo>=1.3\" は要求事項識別子であり、 \"foo\" の部分がプロジェクトの名称で、 " +"\">=1.3\" の部分は :term:`バージョン指定子 ` です" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 +#: ../source/glossary.rst:215 +msgid "Requirements File" +msgstr "Requirementsファイル" + +#: ../source/glossary.rst:218 msgid "" -"In other resources you may encounter references to using ``python setup.py " -"register`` and ``python setup.py upload``. These methods of registering and " -"uploading a package are **strongly discouraged** as it may use a plaintext " -"HTTP or unverified HTTPS connection on some Python versions, allowing your " -"username and password to be intercepted during transmission." +"A file containing a list of :term:`Requirements ` that can be " +"installed using :ref:`pip`. For more information, see the :ref:`pip` docs " +"on :ref:`pip:Requirements Files`." msgstr "" -"他のリソースでは、 ``python setup.py register`` と ``python setup.py " -"upload`` に遭遇するかもしれません。これらのメソッドはパッケージを登録ないし" -"アップロードするものですが、 いくつかのバージョンのPythonで使うと平文のHTTPか" -"検証しないHTTPSを用いるのであなたのユーザ名とパスワードが 通信経路上で横取り" -"される恐れがあって **強く非推奨** の状態になっています。" +":ref:`pip`を用いてインストールできるように :term:`要求事項 ` を" +"記したファイル。詳しい情報は、 :ref:`pip` のドキュメントの :ref:`pip:" +"Requirementsファイル ` をみてください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:520 +#: ../source/glossary.rst:222 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:223 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:226 msgid "" -"The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " -"ensure safety of all users, certain kinds of URLs and directives are " -"forbidden or stripped out (e.g., the ``.. raw::`` directive). **Before** " -"trying to upload your distribution, you should check to see if your brief / " -"long descriptions provided in :file:`setup.py` are valid. You can do this " -"by running :std:doc:`twine check ` on your package files:" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." msgstr "" -"PyPIで使っている reStructuredText パーサは Sphinx **ではありません！** その" -"上、全ユーザの安全を確保するためにある種の URL やディレクティブ(例えば ``.. " -"raw::`` ディレクティブ)は禁止されていたり削除されたりしています。あなたの配布" -"物をアップロードしてみる **前に** :file:`setup.py` の中の brief/long " -"description が文法的に妥当かどうかを確かめるべきです。あなたのパッケージの" -"ファイル群に対して :std:doc:`twine check ` を走らせれば、それを確かめ" -"ることができます。" +":ref:`distutils`や :ref:`setuptools` で使われるプロジェクトの仕様を記したファ" +"イル。 :term:`pyproject.toml`も見てください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:533 -msgid "Create an account" -msgstr "アカウントを作成する" +#: ../source/glossary.rst:229 +msgid "Source Archive" +msgstr "ソースコードアーカイブ" -#: ../source/guides/distributing-packages-using-setuptools.rst:535 +#: ../source/glossary.rst:232 msgid "" -"First, you need a :term:`PyPI ` user account. " -"You can create an account `using the form on the PyPI website `_." +"An archive containing the raw source code for a :term:`Release`, prior to " +"creation of a :term:`Source Distribution ` or :term:`Built Distribution`." msgstr "" -"まず、 :term:`PyPI ` のユーザアカウントが必要で" -"す。 `PyPIウェブサイトにあるフォームを使えば `_ アカウントを作成することができます。" +":term:`ソースコード配布物 ` や :term:`ビ" +"ルド配布物 ` という用語を作る前には、:term:`リリース " +"`向けに生のソースコードを収めたアーカイブのことをこう呼んでいた。" -#: ../source/guides/distributing-packages-using-setuptools.rst:539 -msgid "" -"Now you'll create a PyPI `API token`_ so you will be able to securely upload " -"your project." +#: ../source/glossary.rst:236 +msgid "Source Distribution (or \"sdist\")" msgstr "" -"次に PyPI の `API トークン`_ を作成して、プロジェクトを安全にアップロードでき" -"るようにしましょう。" +"`ソースコード配布物 (またはsdist) `" -#: ../source/guides/distributing-packages-using-setuptools.rst:542 +#: ../source/glossary.rst:239 +#, fuzzy 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." +"A :term:`distribution ` format (usually generated " +"using ``python -m build --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`. See :ref:`package-formats` for more " +"information." msgstr "" -"https://pypi.org/manage/account/#api-tokens and create へ行って、新しい `API " -"トークン`_ を作成してください; これから新しいプロジェクトを作成するわけですか" -"ら、スコープを特定のプロジェクトに限定しないようにしてください。" +":ref:`pip`のようなツールでインストールする時や :term:`ビルド配布物 ` を生成する時に必要なメタデータと必須ソースコードを提供する、" +"(通常は ``python -m build --sdist`` を使って生成される) :term:`配布物 " +"` フォーマット 。" -#: ../source/guides/distributing-packages-using-setuptools.rst:546 +#: ../source/glossary.rst:245 +msgid "System Package" +msgstr "システムパッケージ" + +#: ../source/glossary.rst:248 msgid "" -"**Don't close the page until you have copied and saved the token — you won't " -"see that token again.**" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." msgstr "" -"**トークンをコピーして保存するまではページを閉じないでください -- トークンは" -"二度と表示されることがありません。**" +"rpmやdpkgのように、オペレーティングシステムに固有のフォーマットで提供される" +"パッケージ。" -#: ../source/guides/distributing-packages-using-setuptools.rst:549 +#: ../source/glossary.rst:251 +msgid "Version Specifier" +msgstr "バージョン指定子" + +#: ../source/glossary.rst:254 msgid "" -"To avoid having to copy and paste the token every time you upload, you can " -"create a :file:`$HOME/.pypirc` file:" +"The version component of a :term:`Requirement Specifier`. For example, the " +"\">=1.3\" portion of \"foo>=1.3\". Read the :ref:`Version specifier " +"specification ` for a full description of the specifiers " +"that Python packaging currently supports. Support for this specification " +"was implemented in :ref:`setuptools` v8.0 and :ref:`pip` v6.0." msgstr "" -":file:`$HOME/.pypirc` ファイルを作っておくことで、アップロードするたびにトー" -"クンをコピー・ペーストする手間を省くことができます。" +":term:`要求事項指定子 ` のバージョン部分。例え" +"ば、\"foo>=1.3\" の中の \">=1.3\" の部分。\n" +"Python のパッケージングで現在サポートされている識別子の完全な記述について" +"は、 :ref:`バージョン指定子の仕様 ` を読んでください。こ" +"の仕様のサポートは、 :ref:`setuptools` v8.0 と :ref:`pip` v6.0 で実装されまし" +"た。" -#: ../source/guides/distributing-packages-using-setuptools.rst:558 -msgid "**Be aware that this stores your token in plaintext.**" -msgstr "" -"**このファイルにはトークンが平文で保存されていることに注意してください。**" +#: ../source/glossary.rst:259 +msgid "Virtual Environment" +msgstr "仮想環境" -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -#: ../source/guides/migrating-to-pypi-org.rst:74 -#: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:84 +#: ../source/glossary.rst:262 msgid "" -"For more details, see the :ref:`specification ` for :file:`.pypirc`." +"An isolated Python environment that allows packages to be installed for use " +"by a particular application, rather than being installed system wide. For " +"more information, see the section on :ref:`Creating and using Virtual " +"Environments`." msgstr "" -":file:`.pypirc` についてさらに詳しく知りたい場合は :ref:`specification " -"` を見てください。" +"システム全体からではなく、ある特定のアプリケーションだけから使えるようにパッ" +"ケージをインストールすることができる、隔離されたPython環境。詳細は :ref:`仮想" +"環境の生成と使用 ` using :ref:`twine`." +"The standard :term:`Built Distribution` format. See :ref:`package-formats` " +"for more information." msgstr "" -"アカウントが入手できれば、 :ref:`twine` を使ってあなたの配布物を :term:`PyPI " -"` へアップロードすることができます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/glossary.rst:271 +msgid "Working Set" +msgstr "動作可能セット" + +#: ../source/glossary.rst:274 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." +"A collection of :term:`distributions ` available for " +"importing. These are the distributions that are on the `sys.path` variable. " +"At most, one :term:`Distribution ` for a project is " +"possible in a working set." msgstr "" -"リリースをアップロードする手続きは、そのプロジェクトがPyPIに既に存在していて" -"も存在していなくても同じです - もしまだ存在していなければ、最初にリリースが" -"アップロードされたときに自動的に作成されます。" +"一連のインポート可能な :term:`配布物 `。これらは `sys." +"path` 変数から検索できる配布物です。あるプロジェクトには、高々(訳註、at most" +"ではなくat least、すくなくとも、か。)ひとつの :term:`配布物 ` が動作可能セットにあります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:575 +#: ../source/guides/analyzing-pypi-package-downloads.rst:3 +msgid "Analyzing PyPI package downloads" +msgstr "PyPIパッケージのダウンロード状況の解析" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 msgid "" -"For the second and subsequent releases, PyPI only requires that the version " -"number of the new release differ from any previous releases." +"This section covers how to use the public PyPI download statistics dataset " +"to learn more about downloads of a package (or packages) hosted on PyPI. For " +"example, you can use it to discover the distribution of Python versions used " +"to download a package." msgstr "" -"２回目やそれ以降のリリースで PyPI が要求するのは、新しいリリースのバージョン" -"番号が先行するすべてのリリースとは異なるものであることだけです。" +"この節では、公開のPyPIダウンロードデータセットを用いて、PyPIにホストされてい" +"るパッケージ(あるいはパッケージ群)のダウンロード状況を詳しく見ていくことを記" +"述しています。例えば、ダウンロードに使われたPythonのバージョンの分布を発見す" +"ることができます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/analyzing-pypi-package-downloads.rst:12 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "背景" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "PyPIはいくつもの理由からダウンロード統計を表示しません。:[#]_" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 msgid "" -"You can see if your package has successfully uploaded by navigating to the " -"URL ``https://pypi.org/project/`` where ``sampleproject`` is " -"the name of your project that you uploaded. It may take a minute or two for " -"your project to appear on the site." +"**Inefficient to make work with a Content Distribution Network (CDN):** " +"Download statistics change constantly. Including them in project pages, " +"which are heavily cached, would require invalidating the cache more often, " +"and reduce the overall effectiveness of the cache." msgstr "" -"``sampleproject`` のところをアップロードしているプロジェクトの名前に置き換え" -"るとして、 ``https://pypi.org/project/`` に誘導されれば、あな" -"たのパッケージのアップロードは成功です。あなたのプロジェクトがサイト上に表示" -"されるまでには1,2分の時間がかかるかもしれません。" +"**コンテンツデリバリネットワーク(CDN)と一緒に動かす時の効率の悪さ** ダウン" +"ロード用系は常に変動します。プロジェクトのページでのダウンロードは強烈に" +"キャッシュされていますが、(訳註、統計を正しく取ろうとするなら)より頻繁に" +"キャッシュし直さなければならず、これはキャッシュの効率性を損ねます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 -#: ../source/tutorials/installing-packages.rst:670 +#: ../source/guides/analyzing-pypi-package-downloads.rst:21 msgid "" -"Depending on your platform, this may require root or Administrator access. :" -"ref:`pip` is currently considering changing this by `making user installs " -"the default behavior `_." +"**Highly inaccurate:** A number of things prevent the download counts from " +"being accurate, some of which include:" msgstr "" -"あなたのプラットフォームに依りますが、これにはrootまたはAdministratorの権限で" -"アクセスしなければならないかもしれません。 :ref:`pip` は現在、 `一般ユーザで" -"のインストールを規定動作にする案 `_ にあるように、この部分の変更を検討しています。" +"**非常に不正確** 次に挙げるものを含め、いくつもの要因でダウンロード数が正確と" +"は言えないものになります：" -#: ../source/guides/dropping-older-python-versions.rst:5 -msgid "Dropping support for older Python versions" -msgstr "古いバージョンのPython へのサポートをやめる" +#: ../source/guides/analyzing-pypi-package-downloads.rst:24 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "``pip``のダウンロードキャッシュ (ダウンロード数を小さくする)" -#: ../source/guides/dropping-older-python-versions.rst:7 +#: ../source/guides/analyzing-pypi-package-downloads.rst:25 msgid "" -"Dropping support for older Python versions is supported by the standard :ref:" -"`core-metadata` 1.2 specification via a \"Requires-Python\" attribute." +"Internal or unofficial mirrors (can both raise or lower download counts)" msgstr "" -"古いバージョンのPythonへのサポート取りやめは、標準的な :ref:`core-metadata` " -"1.2 仕様の \"Requires-Python\" アトリビュートでサポートされています。" +"内部の、または、非公式のミラーサイト (ダウンロード数を大きくする要因にも小さ" +"くする要因にもなる)" -#: ../source/guides/dropping-older-python-versions.rst:9 +#: ../source/guides/analyzing-pypi-package-downloads.rst:26 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "PyPIにホストされていないパッケージ (比較することの妥当性を損ねる)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 msgid "" -"Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification " -"by matching the current Python runtime and comparing it with the required " -"version in the package metadata. If they do not match, it will attempt to " -"install the last package distribution that supported that Python runtime." +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" msgstr "" -"Pip 9.0+ のような Metadata 1.2+ のクライアントは、動作中の Python ランタイム" -"のバージョンとパッケージのメタデータで要求されているバージョンを比較突合する" -"ことで、この仕様を遵守しようとします。もし両者が一致しなければ、その Python " -"ランタイムでサポートされているパッケージ配布物の中で最新のものをインストール" -"しようと試みます。" +"ダウンロード数を増やす非公式のスクリプトまたは試行 (ダウンロード数を大きくす" +"る)" -#: ../source/guides/dropping-older-python-versions.rst:12 +#: ../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 "" -"This mechanism can be used to drop support for older Python versions, by " -"amending the \"Requires-Python\" attribute in the package metadata." +"**Not particularly useful:** Just because a project has been downloaded a " +"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 "" -"パッケージのメタデータにある \"Requires-Python\" 属性を修正することで、古い" -"バージョンの Python へのサポートを削除するのにこのメカニズムを利用することが" -"できます。" +"**とりわけ利用価値があるというわけではない** プロジェクト(の配布物、訳註。)が" +"たくさんダウンロードされたからといってそれだけで良いことだと決まったわけでは" +"ありませんし、あまりダウンロードされなかったとしてもそれだけで悪いことだと決" +"めつけることもできません！" -#: ../source/guides/dropping-older-python-versions.rst:14 +#: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"This guide is specifically for users of :ref:`setuptools`, other packaging " -"tools such as ``flit`` may offer similar functionality but users will need " -"to consult relevant documentation." +"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 "" -"このガイドは特に :ref:`setuptools` のユーザに向けて書かれていますので、同様の" -"機能を提供する ``flit`` のような他のパッケージングツールのユーザは適切な文書" -"を参照する必要があるでしょう。" - -#: ../source/guides/dropping-older-python-versions.rst:17 -msgid "Requirements" -msgstr "要求事項" +"まとめると、様々な理由からその価値が低い上、動作させるために犠牲になるものが" +"多いので、限られた資源の効率的な利用にはならないのです。" -#: ../source/guides/dropping-older-python-versions.rst:19 -msgid "This workflow requires that:" -msgstr "このワークフローは、以下を要求します:" +#: ../source/guides/analyzing-pypi-package-downloads.rst:40 +msgid "Public dataset" +msgstr "公開データセット" -#: ../source/guides/dropping-older-python-versions.rst:21 -msgid "The publisher is using the latest version of :ref:`setuptools`," +#: ../source/guides/analyzing-pypi-package-downloads.rst:42 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." msgstr "" -"(パッケージを)公開しようとするものが最新版の :ref:`setuptools` を使っていて、" +"別の方法としては、 `Linehaulプロジェクト `__ がダウンロードのログをPyPIから `Google BigQuery`_ [#]_ へ" +"連続的に取り出して、公開のデータセットとして保管しています。" -#: ../source/guides/dropping-older-python-versions.rst:22 -msgid "The latest version of :ref:`twine` is used to upload the package," -msgstr "最新版の :ref:`twine` を使ってパッケージのアップロードを行い、" +#: ../source/guides/analyzing-pypi-package-downloads.rst:47 +msgid "Getting set up" +msgstr "セットアップのやり方" -#: ../source/guides/dropping-older-python-versions.rst:23 +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 msgid "" -"The user installing the package has at least Pip 9.0, or a client that " -"supports the Metadata 1.2 specification." +"In order to use `Google BigQuery`_ to query the `public PyPI download " +"statistics dataset`_, you'll need a Google account and to enable the " +"BigQuery API on a Google Cloud Platform project. You can run up to 1TB of " +"queries per month `using the BigQuery free tier without a credit card " +"`__" msgstr "" -"パッケージをインストールしようとするユーザが、少なくとも Pip 9.0 か、または、" -"Metadata 1.2 の仕様を満足するクライアントを使っていること。" +"`Google BigQuery`_ を使って `PyPIダウンロード統計の公開データセット `_ に問い合わせを行うためには、まずGoogleア" +"カウントが必要で、Google Cloud Platform (GCP)でBigQuery APIを有効にしておく必" +"要があります。`クレジットカード登録なしのBigQuery 無料枠 `__ を使うと一ヶ月当たり1TBまでのクエリを走らせ" +"ることができます" -#: ../source/guides/dropping-older-python-versions.rst:26 -msgid "Dealing with the universal wheels" -msgstr "universal wheelsの取り扱い" +#: ../source/guides/analyzing-pypi-package-downloads.rst:55 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "`BigQuery ウェブ UI `_ への道案内。" -#: ../source/guides/dropping-older-python-versions.rst:28 +#: ../source/guides/analyzing-pypi-package-downloads.rst:56 +msgid "Create a new project." +msgstr "新しいプロジェクトを作成する。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 msgid "" -"Traditionally, projects providing Python code that is semantically " -"compatible with both Python 2 and Python 3, produce :term:`wheels ` " -"that have a ``py2.py3`` tag in their names. When dropping support for Python " -"2, it is important not to forget to change this tag to just ``py3``. It is " -"often configured within :file:`setup.cfg` under the ``[bdist_wheel]`` " -"section by setting ``universal = 1`` if they use setuptools." +"Enable the `BigQuery API `__." msgstr "" -"伝統的には、Python 2 と Python 3 の両方で文法的に互換性のある Python ソース" -"コードを提供するプロジェクトは、 ``py2.py3`` というタグをその名前の中に持つ :" -"term:`wheels ` を生成しています。 Python 2 へのサポートをやめる時に" -"は、このタグをただの ``py3`` に変更するのを忘れないことが重要です。 " -"setuptools を使っているのであれば、 :file:`setup.cfg` の中の " -"``[bdist_wheel]`` セクションで ``universal=1`` として設定されています。" +"`BigQuery API `__ を有効にする。" -#: ../source/guides/dropping-older-python-versions.rst:36 +#: ../source/guides/analyzing-pypi-package-downloads.rst:60 msgid "" -"If you use this method, either remove this option or section, or explicitly " -"set ``universal`` to ``0``:" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." msgstr "" -"このメソッドを使うのであれば、このオプションないしセクションを削除するか、ま" -"たは、明示的に ``universal`` を ``0`` に設定してください。" +"BigQueryの始め方についてさらに詳しい指南が欲しい場合は、`Cloud Console を使用" +"したクイックスタート `__ を参照してください。" -#: ../source/guides/dropping-older-python-versions.rst:48 +#: ../source/guides/analyzing-pypi-package-downloads.rst:66 +msgid "Data schema" +msgstr "データ構造" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 msgid "" -"Since it is possible to override the :file:`setup.cfg` settings via CLI " -"flags, make sure that your scripts don't have ``--universal`` in your " -"package creation scripts." +"Linehaul writes an entry in a ``bigquery-public-data.pypi.file_downloads`` " +"table for each download. The table contains information about what file was " +"downloaded and how it was downloaded. Some useful columns from the `table " +"schema `__ include:" msgstr "" -"CLIでオプションを指定することで :file:`setup.cfg` ファイルでの設定を上書きす" -"ることができるので、あなたのパッケージ生成スクリプトが ``--universal`` オプ" -"ションを指定していないことを確実にしてください。" +"それぞれのダウンロードの情報を格納した ``bigquery-public-data.pypi." +"file_downloads``テーブルについての説明をLinehaulが書きました。このテーブル" +"は、どのファイルがどのようにダウンロードされたかに関する情報を格納していま" +"す。`テーブル構造 `__ から役に" +"立つカラムをいくつか挙げると：" -#: ../source/guides/dropping-older-python-versions.rst:53 -msgid "Defining the Python version required" -msgstr "要求する Python のバージョンを定義する" +#: ../source/guides/analyzing-pypi-package-downloads.rst:75 +msgid "Column" +msgstr "カラム" -#: ../source/guides/dropping-older-python-versions.rst:56 -msgid "1. Download the newest version of Setuptools" -msgstr "1. Setuptools の最新版をダウンロードする" +#: ../source/guides/analyzing-pypi-package-downloads.rst:75 +#: ../source/specifications/core-metadata.rst:194 +msgid "Description" +msgstr "説明" -#: ../source/guides/dropping-older-python-versions.rst:58 -msgid "" -"Ensure that before you generate source distributions or binary " -"distributions, you update Setuptools and install twine." -msgstr "" -"ソースコード配布物を生成するにせよ、バイナリ配布物を生成するにせよ、 " -"Setuptools を更新し twine をインストールするようにしてください。" +#: ../source/guides/analyzing-pypi-package-downloads.rst:75 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/version-specifiers.rst:1067 +msgid "Examples" +msgstr "例" -#: ../source/guides/dropping-older-python-versions.rst:60 -msgid "Steps:" -msgstr "手順:" +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "timestamp" +msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:74 -msgid "``setuptools`` version should be above 24.0.0." -msgstr "``setuptools`` のバージョンが 24.0.0 以上であること。" +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Date and time" +msgstr "日付と時刻" -#: ../source/guides/dropping-older-python-versions.rst:77 -msgid "2. Specify the version ranges for supported Python distributions" -msgstr "2. サポートする Python 配布物のバージョンの範囲を指定する" +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:79 -msgid "" -"You can specify version ranges and exclusion rules, such as at least Python " -"3. Or, Python 2.7, 3.4 and beyond." +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "file.project" msgstr "" -"「少なくとも Python 3」や「Python 2.7 か Python 3.5 とそれ以上」などというよ" -"うに、バージョンの範囲や除外のルールを指定することができます。" -#: ../source/guides/dropping-older-python-versions.rst:81 -msgid "Examples:" -msgstr "例:" +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Project name" +msgstr "プロジェクト名" -#: ../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``." +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.version" msgstr "" -"このような値の設定は、 :file:`setup.py` スクリプトの中の ``setup`` の呼び出し" -"の中で行えます。 ``python_requires`` 引数に設定した内容に基づいて ``Requires-" -"Python`` メタデータの値が挿入されます。" -#: ../source/guides/dropping-older-python-versions.rst:103 -msgid "3. Validating the Metadata before publishing" -msgstr "3. 公開の前にメタデータを検証する" +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Package version" +msgstr "パッケージのバージョン" -#: ../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." +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``0.1.6``, ``1.4.2``" msgstr "" -"Python のソースコードパッケージ (あなたがダウンロードしたzipファイルやtar.gz" -"ファイル) の中には、PKG-INFO という名前のテキストファイルがあります。" -#: ../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." +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "details.installer.name" msgstr "" -"このファイルは :ref:`distutils` や :ref:`setuptools` でソースコードパッケージ" -"を作成する時に一緒に作成されます。その内容は、一連のキーと値の組み合わせで、" -"キーは Pypa 標準メタデータフォーマットの一部です。" -#: ../source/guides/dropping-older-python-versions.rst:110 -msgid "You can see the contents of the generated file like this:" -msgstr "生成されたファイルの内容はこのようになっています:" +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Installer" +msgstr "インストーラ" -#: ../source/guides/dropping-older-python-versions.rst:116 -msgid "Validate that the following is in place, before publishing the package:" -msgstr "パッケージを公開する前に、以下のことが適切かどうかを検証してください。" +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "pip, :ref:`bandersnatch`" +msgstr "pip、 :ref:`bandersnatch`" -#: ../source/guides/dropping-older-python-versions.rst:118 -msgid "" -"If you have upgraded correctly, the Metadata-Version value should be 1.2 or " -"higher." +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.python" msgstr "" -"アップグレードが正しく終われば、Metadata-Version の値が 1.2 かそれ以上になっ" -"ているはずです。" -#: ../source/guides/dropping-older-python-versions.rst:119 -msgid "" -"The Requires-Python field is set and matches your specification in setup.py." +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Python version" +msgstr "Pythonバージョン" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "``2.7.12``, ``3.6.4``" msgstr "" -"Requires-Python フィールドが設定されていて、setup.py でのあなたの指定に一致し" -"ているはずです。" -#: ../source/guides/dropping-older-python-versions.rst:122 -msgid "4. Using Twine to publish" -msgstr "4. Twineを使って公開する" +#: ../source/guides/analyzing-pypi-package-downloads.rst:90 +msgid "Useful queries" +msgstr "役に立つクエリ" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 msgid "" -"Twine has a number of advantages, apart from being faster it is now the " -"supported method for publishing packages." +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." msgstr "" -"動作が速いことを別にしてもTwineには数多くの利点があり、今ではパッケージを公開" -"するためのメソッドとしてサポートされています。" +"「クエリを新規作成」ボタンをクリックすることで `BigQuery web UI`_ 内でクエリ" +"を走らせましょう。" -#: ../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/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Note that the rows are stored in a partitioned table, which helps limit the " +"cost of queries. These example queries analyze downloads from recent history " +"by filtering on the ``timestamp`` column." +msgstr "" +"クエリのコストを削減するためにデータベースの行がパーティションされた状態で格" +"納されていることを覚えておいてください。これらの例では、``timestamp`` カラム" +"を使って絞り込むことで最近のダウンロード履歴を分析しています。" -#: ../source/guides/dropping-older-python-versions.rst:129 -msgid "Dropping a Python release" -msgstr "Pythonリリースをサポートから外す" +#: ../source/guides/analyzing-pypi-package-downloads.rst:99 +msgid "Counting package downloads" +msgstr "パッケージのダウンロードを数える" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 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." +"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 +#: ../source/guides/analyzing-pypi-package-downloads.rst:165 +#: ../source/guides/analyzing-pypi-package-downloads.rst:202 +msgid "num_downloads" msgstr "" -"Requires-Python メタデータ付きでパッケージを公開しさえすれば、次回以降の更新" -"の際にPython ランタイムをサポートから外すことができるようになります。" -#: ../source/guides/dropping-older-python-versions.rst:133 -msgid "It must be done in this order for the automated fallback to work." +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +msgid "26190085" msgstr "" -"自動フォールバックが正しく動作するためには、この順番で行わなければなりませ" -"ん。" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/analyzing-pypi-package-downloads.rst:121 msgid "" -"For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " -"of your package." +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." msgstr "" -"例えば、 Requires-Python: \">=2.7\" の状態であなたのパッケージのバージョン " -"1.0.0 を公開したとしましよう。" +"pipを通じてダウンロードされた数だけを数えるには、``details.installer.name``カ" +"ラムを使って抽出してください。" -#: ../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 " -"2.7 will have version 1.0.0 of the package installed, and any >=3.5 users " -"will receive version 2.0.0." +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +msgid "24334215" msgstr "" -"その後、バージョン文字列を \">=3.5\" に修正した新しいバージョン 2.0.0 のパッ" -"ケージを公開すれば、Pip 9.0+ を 2.7 で使っているユーザはバージョン 1.0.0. の" -"パッケージをインストールし、>=3.5 のユーザはバージョン 2.0.0 を受け取ることに" -"なるでしょう。" -#: ../source/guides/hosting-your-own-index.rst:5 -msgid "Hosting your own simple repository" -msgstr "あなた自身の単純なリポジトリをホストする" +#: ../source/guides/analyzing-pypi-package-downloads.rst:143 +msgid "Package downloads over time" +msgstr "時系列のパッケージダウンロード数" -#: ../source/guides/hosting-your-own-index.rst:8 +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 msgid "" -"If you wish to host your own simple repository [1]_, you can either use a " -"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." +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." msgstr "" -"あなた自身の単純なリポジトリ [1]_ をホストしたいのであれば、 :doc:`devpi " -"` のようなソフトウェアパッケージを使うこともできますし、単に " -"web サーバ上に適切なディレクトリを作成して静的ファイルを提供し自動でインデッ" -"クスを生成させることも可能です。" +"月毎のダウンロード数を数えるには、``TIMESTAMP_TRUNC``関数を使います。このカラ" +"ムを使って抽出することは、通信量を抑えることにもなります。" -#: ../source/guides/hosting-your-own-index.rst:13 -msgid "" -"In either case, since you'll be hosting a repository that is likely not in " -"your user's default repositories, you should instruct them in your project's " -"description to configure their installer appropriately. For example with pip:" +#: ../source/guides/analyzing-pypi-package-downloads.rst:165 +msgid "month" msgstr "" -"どちらの場合でも、ユーザとしての既定のリポジトリではない場所をあなたのリポジ" -"トリにしようとしているのでしょうから、あなたのプロジェクトの説明にインストー" -"ラを適切に設定するように指図しておくべきでしょう。例えば pip なら:" -#: ../source/guides/hosting-your-own-index.rst:29 -msgid "" -"In addition, it is **highly** recommended that you serve your repository " -"with valid HTTPS. At this time, the security of your user's installations " -"depends on all repositories using a valid HTTPS setup." +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "2018-01-01" msgstr "" -"加えて、あなたのリポジトリを公開する場合はHTTPSで公開することが強く推奨されま" -"す。この時、ユーザがあなたのパッケージをインストールする際のセキュリティは、" -"すべてのリポジトリが適切なHTTPS設定であるか否かに依存します。" -#: ../source/guides/hosting-your-own-index.rst:35 -msgid "\"Manual\" repository" -msgstr "\"手動\"リポジトリ" +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2344692" +msgstr "2344692" -#: ../source/guides/hosting-your-own-index.rst:37 -msgid "" -"The directory layout is fairly simple, within a root directory you need to " -"create a directory for each project. This directory should be the :ref:" -"`normalized name ` of the project. Within each of these " -"directories simply place each of the downloadable files. If you have the " -"projects \"Foo\" (with the versions 1.0 and 2.0) and \"bar\" (with the " -"version 0.1) You should end up with a structure that looks like::" -msgstr "" -"ディレクトリ構造は極めて単純で、ルートディレクトリ内に各プロジェクトを納めた" -"ディレクトリを作成する必要があります。このディレクトリは、プロジェクトの :" -"ref:`標準化された名前 ` になっているべきです。各プロジェ" -"クトのディレクトリには、それぞれダウンロード可能なファイルを置くだけで" -"す。\"Foo\" というプロジェクト (のバージョン 1.0 と 2.0) と \"bar\" というプ" -"ロジェクト (のバージョン 0.1) があるなら、ディレクトリ構造はこんなふうになる" -"でしょう::" +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2017-12-01" +msgstr "2017-12-01" -#: ../source/guides/hosting-your-own-index.rst:50 -msgid "" -"Once you have this layout, simply configure your webserver to serve the root " -"directory with autoindex enabled. For an example using the built in Web " -"server in `Twisted`_, you would simply run ``twistd -n web --path .`` and " -"then instruct users to add the URL to their installer's configuration." -msgstr "" -"この配置ができあがったら、あとはルートディレクトリを自動インデックス付きで" -"ウェブサーバから提供するように設定するだけです。 `Twisted`_ の組み込みウェブ" -"サーバを使う例では、単に ``twisted -n web --path.`` を走らせておいて、ユーザ" -"に対してこのURLをインストーラの設定に加えるように指示するだけです。" +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "1730398" +msgstr "1730398" -#: ../source/guides/hosting-your-own-index.rst:57 -#: ../source/guides/index-mirrors-and-caches.rst:47 -msgid "Existing projects" -msgstr "既存のプロジェクト" +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-11-01" +msgstr "2017-11-01" -#: ../source/guides/hosting-your-own-index.rst:63 -msgid "Package upload" -msgstr "パッケージアップロード" +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:181 +msgid "Python versions over time" +msgstr "時系列で見たPythonバージョン" -#: ../source/guides/hosting-your-own-index.rst:64 -msgid "PyPI fall-through [2]_" -msgstr "PyPI フォールスルー [2]_" +#: ../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 "" +"``details.python``カラムからPythonのバージョンを取り出します。警告：このクエ" +"リは500GB以上のデータを処理します。" -#: ../source/guides/hosting-your-own-index.rst:65 -#: ../source/guides/index-mirrors-and-caches.rst:56 -#: ../source/guides/supporting-windows-using-appveyor.rst:146 -msgid "Additional notes" -msgstr "補遺" +#: ../source/guides/analyzing-pypi-package-downloads.rst:202 +msgid "python" +msgstr "python" -#: ../source/guides/hosting-your-own-index.rst:67 -#: ../source/guides/index-mirrors-and-caches.rst:58 -msgid ":ref:`devpi`" -msgstr ":ref:`devpi`" +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "3.7" +msgstr "3.7" -#: ../source/guides/hosting-your-own-index.rst:68 -#: ../source/guides/hosting-your-own-index.rst:69 -#: ../source/guides/hosting-your-own-index.rst:75 -#: ../source/guides/hosting-your-own-index.rst:79 -#: ../source/guides/hosting-your-own-index.rst:99 -#: ../source/guides/hosting-your-own-index.rst:120 -#: ../source/guides/index-mirrors-and-caches.rst:59 -#: ../source/guides/index-mirrors-and-caches.rst:60 -#: ../source/guides/index-mirrors-and-caches.rst:66 -#: ../source/guides/index-mirrors-and-caches.rst:67 -#: ../source/guides/index-mirrors-and-caches.rst:74 -#: ../source/guides/index-mirrors-and-caches.rst:78 -#: ../source/guides/index-mirrors-and-caches.rst:80 -#: ../source/guides/index-mirrors-and-caches.rst:85 -#: ../source/guides/index-mirrors-and-caches.rst:86 -#: ../source/guides/index-mirrors-and-caches.rst:90 -#: ../source/guides/index-mirrors-and-caches.rst:92 -#: ../source/guides/index-mirrors-and-caches.rst:96 -#: ../source/guides/index-mirrors-and-caches.rst:98 -#: ../source/guides/index-mirrors-and-caches.rst:102 -#: ../source/guides/index-mirrors-and-caches.rst:104 -#: ../source/guides/index-mirrors-and-caches.rst:108 -#: ../source/guides/index-mirrors-and-caches.rst:110 -msgid "✔" -msgstr "✔" +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "18051328726" +msgstr "18051328726" -#: ../source/guides/hosting-your-own-index.rst:70 -msgid "" -"multiple indexes with inheritance, with syncing, replication, fail-over; " -"mirroring" -msgstr "同期、複製、フェールオーバ、ミラーリングが可能な複数のインデックス" +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.6" +msgstr "3.6" -#: ../source/guides/hosting-your-own-index.rst:73 -#: ../source/guides/index-mirrors-and-caches.rst:71 -msgid ":ref:`simpleindex`" -msgstr ":ref:`simpleindex`" +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "9635067203" +msgstr "9635067203" -#: ../source/guides/hosting-your-own-index.rst:78 -msgid ":ref:`pypiserver`" -msgstr ":ref:`pypiserver`" +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.8" +msgstr "3.8" -#: ../source/guides/hosting-your-own-index.rst:83 -msgid ":ref:`pypiprivate`" -msgstr ":ref:`pypiprivate`" +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "7781904681" +msgstr "7781904681" -#: ../source/guides/hosting-your-own-index.rst:88 -#: ../source/guides/index-mirrors-and-caches.rst:77 -msgid ":ref:`pypicloud`" -msgstr ":ref:`pypicloud`" +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "2.7" +msgstr "2.7" -#: ../source/guides/hosting-your-own-index.rst:91 -msgid "unmaintained; also cached proxying; authentication, authorisation" -msgstr "メンテナンスされていない; またプロクシでキャッシュ; 認証、認可" +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "6381252241" +msgstr "6381252241" -#: ../source/guides/hosting-your-own-index.rst:93 -msgid ":ref:`pywharf`" -msgstr ":ref:`pywharf`" +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "null" +msgstr "" -#: ../source/guides/hosting-your-own-index.rst:96 -msgid "unmaintained; serve files in GitHub" -msgstr "メンテナンスされていない; GitHub内のファイルを提供する" +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2026630299" +msgstr "2026630299" -#: ../source/guides/hosting-your-own-index.rst:98 -#: ../source/guides/index-mirrors-and-caches.rst:83 -msgid ":ref:`pulppython`" -msgstr ":ref:`pulppython`" +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "3.5" +msgstr "3.5" -#: ../source/guides/hosting-your-own-index.rst:101 -msgid "also mirroring, proxying; plugin for Pulp" -msgstr "また、ミラーリング、プロクシ利用; Pulp 用のプラグイン" +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "1894153540" +msgstr "1894153540" -#: ../source/guides/hosting-your-own-index.rst:103 -msgid ":ref:`pip2pi`" -msgstr ":ref:`pip2pi`" +#: ../source/guides/analyzing-pypi-package-downloads.rst:219 +msgid "Getting absolute links to artifacts" +msgstr "アーティファクトへの完全なリンクを得る" -#: ../source/guides/hosting-your-own-index.rst:106 -msgid "also mirroring; manual synchronisation" -msgstr "また、ミラーリング; 手動の同期" +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "" +"It's sometimes helpful to be able to get the absolute links to download " +"artifacts from PyPI based on their hashes, e.g. if a particular project or " +"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/hosting-your-own-index.rst:108 -msgid ":ref:`dumb-pypi`" -msgstr ":ref:`dumb-pypi`" +#: ../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 はいつまでも存在するとは限りませんが、しかし、その時点" +"で PyPI のアーティファクトがどこに保存されているかを示す URL を含んでいます。" -#: ../source/guides/hosting-your-own-index.rst:111 -msgid "not a server, but a static file site generator" -msgstr "サーバではなくて、静的ファイルのサイトのジェネレータ" +#: ../source/guides/analyzing-pypi-package-downloads.rst:240 +msgid "url" +msgstr "url" -#: ../source/guides/hosting-your-own-index.rst:113 -msgid ":ref:`httpserver`" -msgstr ":ref:`httpserver`" +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "" +"https://files.pythonhosted.org/packages/" +"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/hosting-your-own-index.rst:116 -msgid "standard-library" -msgstr "標準ライブラリ" +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/" +"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/hosting-your-own-index.rst:118 -#: ../source/guides/index-mirrors-and-caches.rst:107 -msgid "`Apache `_" -msgstr "`Apache `_" +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/" +"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/hosting-your-own-index.rst:121 -#: ../source/guides/index-mirrors-and-caches.rst:111 +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 msgid "" -"using `mod_rewrite `_ and `mod_cache_disk `_, you can cache requests to package indexes through an " -"Apache server" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" msgstr "" -"`mod_rewrite `_ " -"および `mod_cache_disk `_ を用いて、Apache サーバ経由のパッケージインデックスへ" -"のリクエストをキャッシュすることができます" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" -#: ../source/guides/hosting-your-own-index.rst:131 +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 msgid "" -"For complete documentation of the simple repository protocol, see :ref:" -"`simple repository API `." +"https://files.pythonhosted.org/" +"packages/6f/5b/2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" msgstr "" -"単純なリポジトリプロトコルの完全な説明文書としては、 :ref:`simple repository " -"API ` を見てください。" +"https://files.pythonhosted.org/" +"packages/6f/5b/2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" -#: ../source/guides/hosting-your-own-index.rst:134 +#: ../source/guides/analyzing-pypi-package-downloads.rst:255 +msgid "Caveats" +msgstr "注意書き" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 msgid "" -"Can be configured to fall back to PyPI (or another package index) if a " -"requested package is missing." +"In addition to the caveats listed in the background above, Linehaul suffered " +"from a bug which caused it to significantly under-report download statistics " +"prior to July 26, 2018. Downloads before this date are proportionally " +"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 "" -"要求されたパッケージが存在しなければ、 PyPI (もしくは他のパッケージインデック" -"ス) へフォールバックするように設定しておくことができます。" +"上記の背景に列挙した注意書きに加えて、Linehaulは、極端に過小報告されていたダ" +"ウンロード統計の原因となったバグに2018年7月26日まで悩まされていました。この日" +"より前のダウンロード数については、比率の点(例えばPython2とPython3の百分率)で" +"は正確ですが、絶対数の点では桁が異なるほどに過小です。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:265 +msgid "Additional tools" +msgstr "その他のツール" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +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 "``google-cloud-bigquery``" -#: ../source/guides/index.rst:4 +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 msgid "" -"**Guides** are focused on accomplishing a specific task and assume that you " -"are already familiar with the basics of Python packaging. If you're looking " -"for an introduction to packaging, see :doc:`/tutorials/index`." +"You can also access the public PyPI download statistics dataset " +"programmatically via the BigQuery API and the `google-cloud-bigquery`_ " +"project, the official Python client library for BigQuery." msgstr "" -"**ガイド文書** は特定のタスクを達成することに重点を置くもので、読者が Python " -"のパッケージングの基礎について既に馴染みがあるものと仮定しています。パッケー" -"ジングの導入的な説明を探しているのであれば :doc:`/tutorials/index` を見てくだ" -"さい。" - -#: ../source/guides/index-mirrors-and-caches.rst:5 -msgid "Package index mirrors and caches" -msgstr "パッケージインデックスのミラーとキャッシュ" +"BigQuery APIとBigQuery用の公式Pythonクライアントである `google-cloud-" +"bigquery`_ プロジェクトを使って、プログラムからPyPIの公開ダウンロード統計デー" +"タセットにアクセスすることもできます。" -#: ../source/guides/index-mirrors-and-caches.rst:8 -msgid "2023-11-08" -msgstr "2023年11月8日" +#: ../source/guides/analyzing-pypi-package-downloads.rst:301 +msgid "``pypinfo``" +msgstr "``pypinfo``" -#: ../source/guides/index-mirrors-and-caches.rst:10 +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 msgid "" -"Mirroring or caching of PyPI (and other :term:`package indexes `) can be used to speed up local package installation, allow offline " -"work, handle corporate firewalls or just plain Internet flakiness." +"`pypinfo`_ is a command-line tool which provides access to the dataset and " +"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 "" -"PyPI (あるいは他の :term:`パッケージインデックス `) のミラーや" -"キャッシュがあると、手元でパッケージをインストールするのが速くなったり、オフ" -"ラインでインストールできたり、会社のファイアウォール経由でもできたり、あるい" -"は、単純にインターネットがあてにならなくてもインストールできたりします。" +"`pypinfo`_ はデータセットにアクセスして、役に立つクエリをいくつか生成する機能" +"を提供するコマンドラインツールです。例えば、``pypinfo package_name``を実行す" +"れば、そのパッケージのダウンロード総数を問い合わせることができます。" -#: ../source/guides/index-mirrors-and-caches.rst:15 -msgid "There are multiple classes of options in this area:" -msgstr "この領域のオプションには複数のクラスがあります:" +#: ../source/guides/analyzing-pypi-package-downloads.rst:307 +msgid "Install `pypinfo`_ using pip." +msgstr "pipを用いて `pypinfo`_ をインストール。" -#: ../source/guides/index-mirrors-and-caches.rst:17 -msgid "local/hosted caching of package indexes." -msgstr "パッケージインデックスのローカルまたはホストされたキャッシュ。" +#: ../source/guides/analyzing-pypi-package-downloads.rst:313 +msgid "Usage:" +msgstr "使い方：" -#: ../source/guides/index-mirrors-and-caches.rst:19 -msgid "" -"local/hosted mirroring of a package index. A mirror is a (whole or partial) " -"copy of a package index, which can be used in place of the original index." -msgstr "" -"パッケージインデックスのローカルまたはホストされたミラーリング。ミラーとは、" -"パッケージインデックスの (全体または一部の) コピーで、オリジナルのインデック" -"スの代わりに使うことができます。" +#: ../source/guides/analyzing-pypi-package-downloads.rst:329 +msgid "``pandas-gbq``" +msgstr "``pandas-gbq``" -#: ../source/guides/index-mirrors-and-caches.rst:23 +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 msgid "" -"private package index with fall-through to public package indexes (for " -"example, to mitigate dependency confusion attacks), also known as a proxy." +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." msgstr "" -"(例えば依存関係を混乱させる攻撃を緩和するための) 公開のパッケージインデックス" -"へフォールスルーする機能を持ったプライベートなパッケージインデックスで、プロ" -"クシーとも呼ばれる。" +"`pandas-bbq`_ プロジェクトを使えば `Pandas`_ 経由でクエリ結果を参照することが" +"できます。" -#: ../source/guides/index-mirrors-and-caches.rst:29 -msgid "Caching with pip" -msgstr "pipによるキャッシュ" +#: ../source/guides/analyzing-pypi-package-downloads.rst:335 +#: ../source/specifications/dependency-specifiers.rst:487 +msgid "References" +msgstr "参考文献" -#: ../source/guides/index-mirrors-and-caches.rst:31 +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 msgid "" -"pip provides a number of facilities for speeding up installation by using " -"local cached copies of :term:`packages `:" +"`PyPI Download Counts deprecation email `__" msgstr "" -"pip は、 :term:`パッケージ ` のローカルキャッシュを使っ" -"て素早くインストールするためのいくつもの機能を提供します。" +"`PyPI ダウンロード統計を非推奨とするメール (PyPI Download Counts deprecation " +"email) `__" -#: ../source/guides/index-mirrors-and-caches.rst:34 +#: ../source/guides/analyzing-pypi-package-downloads.rst:338 msgid "" -":ref:`Fast & local installs ` by " -"downloading all the requirements for a project and then pointing pip at " -"those downloaded files instead of going to PyPI." +"`PyPI BigQuery dataset announcement email `__" msgstr "" -"あるプロジェクトの依存先パッケージをすべてダウンロードし、 pip を PyPI の代わ" -"りにそれらダウンロード済みファイルに向けることによる :ref:`速くてローカルなイ" -"ンストール ` 。" +"`PyPI BigQueryデータセットをアナウンスするメール (PyPI BigQuery dataset " +"announcement email) `__" -#: ../source/guides/index-mirrors-and-caches.rst:37 +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "プラグイン作成と発見" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 msgid "" -"A variation on the above which pre-builds the installation files for the " -"requirements using :ref:`python3 -m pip wheel `:" +"Often when creating a Python application or library you'll want the ability " +"to provide customizations or extra features via **plugins**. Because Python " +"packages can be separately distributed, your application or library may want " +"to automatically **discover** all of the plugins available." msgstr "" -":ref:`python -m pip wheel ` を用いて依存先パッケージのインス" -"トール用ファイルをあらかじめビルドしておくという上記のバリエーション:" +"Pythonのアプリケーションまたはライブラリを作成する時には、カスタマイズができ" +"るようにしたり **プラグイン** を通じて機能を追加できるようにしたりすることが" +"しばしばあります。Pythonのパッケージは別々に配布できますので、あなたのアプリ" +"ケーションまたはライブラリが利用可能なすべてのプラグインを自動的に **探し出す" +"** ようにしたくなるかもしれません。" -#: ../source/guides/index-mirrors-and-caches.rst:53 -msgid "Cache" -msgstr "キャッシュ" +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "プラグインの自動検出には大きく分けて３個の実現方法があります。" -#: ../source/guides/index-mirrors-and-caches.rst:54 -msgid "Mirror" -msgstr "ミラー" +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "`命名規則を用いるやり方 `_ 。" -#: ../source/guides/index-mirrors-and-caches.rst:55 -msgid "Proxy" -msgstr "プロクシ" +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "`namespaceパッケージを用いるやり方 `_ 。" -#: ../source/guides/index-mirrors-and-caches.rst:62 -msgid "" -"multiple indexes with inheritance; syncing, replication, fail-over; package " -"upload" -msgstr "" -"継承・同期・複製・フェイルオーバ・パッケージアップロードの機能を持つ複数のイ" -"ンデックス群" +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "`パッケージのメタデータを用いるやり方 `_ 。" -#: ../source/guides/index-mirrors-and-caches.rst:65 -msgid ":ref:`bandersnatch`" -msgstr ":ref:`bandersnatch`" +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "命名規則を用いるやり方" -#: ../source/guides/index-mirrors-and-caches.rst:75 -msgid "custom plugin enables caching; re-routing to other package indexes" +#: ../source/guides/creating-and-discovering-plugins.rst:20 +msgid "" +"If all of the plugins for your application follow the same naming " +"convention, you can use :func:`pkgutil.iter_modules` to discover all of the " +"top-level modules that match the naming convention. For example, `Flask`_ " +"uses the naming convention ``flask_{plugin_name}``. If you wanted to " +"automatically discover all of the Flask plugins installed:" msgstr "" -"カスタムプラグインによってキャッシングや他のパッケージインデックスへのリルー" -"ティングが可能になります" - -#: ../source/guides/index-mirrors-and-caches.rst:81 -msgid "unmaintained; authentication, authorisation" -msgstr "保守されていない; 認証・認可" +"あなたのアプリケーション用のすべてのプラグインが命名規則に従うのであれば、 :" +"func:`pkgutil.iter_modules` を用いて命名規則に合致するトップレベルのすべての" +"モジュールを発見することができます。例えば、 `Flask`_ は命名規則として " +"``flask_{plugin_name}`` を使います。もし、すべてのインストール済みFlask用プラ" +"グインを発見したいのであれば：" -#: ../source/guides/index-mirrors-and-caches.rst:87 -msgid "plugin for Pulp; multiple proxied indexes; package upload" +#: ../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 "" -"Pulp 用のプラグイン; 複数のプロクシされたインデックス; パッケージアップロード" - -#: ../source/guides/index-mirrors-and-caches.rst:89 -msgid ":ref:`proxpi`" -msgstr ":ref:`proxpi`" - -#: ../source/guides/index-mirrors-and-caches.rst:93 -#: ../source/guides/index-mirrors-and-caches.rst:99 -msgid "multiple proxied indexes" -msgstr "複数のプロクシされたインデックス群" - -#: ../source/guides/index-mirrors-and-caches.rst:95 -msgid ":ref:`nginx_pypi_cache`" -msgstr ":ref:`nginx_pypi_cache`" - -#: ../source/guides/index-mirrors-and-caches.rst:101 -msgid ":ref:`flaskpypiproxy`" -msgstr ":ref:`flaskpypiproxy`" +"もしあなたが `Flask-SQLAlchemy`_ と `Flask-Talisman`_ のふたつのプラグインを" +"インストールしてあるなら、 ``discovered_plugins`` は次のようになるでしょう：" -#: ../source/guides/index-mirrors-and-caches.rst:105 -msgid "unmaintained" -msgstr "保守されていない" +#: ../source/guides/creating-and-discovering-plugins.rst:48 +msgid "" +"Using naming convention for plugins also allows you to query the Python " +"Package Index's :ref:`simple repository API ` for all " +"packages that conform to your naming convention." +msgstr "" +"プラグインの命名規則を用いることで、あなたの命名規則に従うすべてのパッケージ" +"についてPython パッケージインデックスの :ref:`simple repository API ` から検索することもできるようになります。" -#: ../source/guides/installing-scientific-packages.rst:5 -msgid "Installing scientific packages" -msgstr "科学分野のパッケージをインストールする" +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "namespaceパッケージを用いるやり方" -#: ../source/guides/installing-scientific-packages.rst:8 +#: ../source/guides/creating-and-discovering-plugins.rst:60 msgid "" -"Scientific software tends to have more complex dependencies than most, and " -"it will often have multiple build options to take advantage of different " -"kinds of hardware, or to interoperate with different pieces of external " -"software." +":doc:`Namespace packages ` can be used to " +"provide a convention for where to place plugins and also provides a way to " +"perform discovery. For example, if you make the sub-package ``myapp." +"plugins`` a namespace package then other :term:`distributions ` can provide modules and packages to that namespace. Once " +"installed, you can use :func:`pkgutil.iter_modules` to discover all modules " +"and packages installed under that namespace:" msgstr "" -"科学分野のソフトウェアは、他のほとんどのものよりも複雑な依存関係を持つことが" -"多く、異なる種類のハードウェアの利点を引き出すためや外部のソフトウェアのさま" -"ざまな部分と協調動作するためのオプションが複数存在することもしばしばです。" +":doc:`Namespace パッケージ ` を使えば、プラグイ" +"ンをどこに配置するかに関する規則や、発見するための方法も提供できます。例え" +"ば、あなたが名前空間を決めるサブパッケージ ``myapp.plugins`` を作成したら、そ" +"の名前空間に他の :term:`配布物 ` がモジュールやパッケー" +"ジを配置することができます。インストールが終われば、あなたは :func:`pkgutil." +"iter_modules` を用いてインストール済みの全てのモジュールやパッケージをその名" +"前空間で発見できるでしょう。" -#: ../source/guides/installing-scientific-packages.rst:13 +#: ../source/guides/creating-and-discovering-plugins.rst:88 msgid "" -"In particular, `NumPy `__, which provides the basis for " -"most of the software in the `scientific Python stack `_ can be configured to interoperate with different FORTRAN " -"libraries, and can take advantage of different levels of vectorised " -"instructions available in modern CPUs." +"Specifying ``myapp.plugins.__path__`` to :func:`~pkgutil.iter_modules` " +"causes it to only look for the modules directly under that namespace. For " +"example, if you have installed distributions that provide the modules " +"``myapp.plugins.a`` and ``myapp.plugins.b`` then ``discovered_plugins`` in " +"this case would be:" msgstr "" -"とりわけ `科学分野のPythonソフトウェア群 `_ の" -"ほとんどのソフトウェアに基盤を提供する`NumPy `__ は、他" -"の FORTRAN ライブラリと協調動作したり現代的なCPUで利用可能なさまざまなレベル" -"のベクター演算命令を活用できるように構成可能です。" +":func:`~pkgutil.iter_modules` に ``myapp.plugins.__path__`` を指定すると、そ" +"の名前空間の直下にあるモジュールだけを探索するようになります。例えば、あなた" +"がモジュールの ``myapp.plugins.a`` と ``myapp.plugins.b`` を提供する配布物を" +"インストールしているとしたら、 ``discovered_plugins`` は次のようになるでしょ" +"う：" -#: ../source/guides/installing-scientific-packages.rst:19 +#: ../source/guides/creating-and-discovering-plugins.rst:100 msgid "" -"Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built " -"32-bit and 64-bit binaries in the ``wheel`` format are available for all " -"major operating systems (Windows, macOS, and Linux) on PyPI. Note, however, " -"that on Windows, NumPy binaries are linked against the `ATLAS `__ BLAS/LAPACK library, restricted to SSE2 instructions, " -"so they may not provide optimal linear algebra performance." +"This sample uses a sub-package as the namespace package (``myapp.plugins``), " +"but it's also possible to use a top-level package for this purpose (such as " +"``myapp_plugins``). How to pick the namespace to use is a matter of " +"preference, but it's not recommended to make your project's main top-level " +"package (``myapp`` in this case) a namespace package for the purpose of " +"plugins, as one bad plugin could cause the entire namespace to break which " +"would in turn make your project unimportable. For the \"namespace sub-" +"package\" approach to work, the plugin packages must omit the :file:" +"`__init__.py` for your top-level package directory (``myapp`` in this case) " +"and include the namespace-package style :file:`__init__.py` in the namespace " +"sub-package directory (``myapp/plugins``). This also means that plugins " +"will need to explicitly pass a list of packages to :func:`setup`'s " +"``packages`` argument instead of using :func:`setuptools.find_packages`." msgstr "" -"Numpy のバージョン 1.10.4 および SciPy のバージョン 1.0.0 以降は、 主要なオペ" -"レーティングシステム (WindowsとmacOSとLinux)向けに32 ビットと 64 ビットのビル" -"ド済みバイナリが ``wheel`` 形式でPyPIに準備されています。ただ、Windowsでは、" -"SSE2命令セットに限定された `ATLAS `__ BLAS/" -"LAPACK ライブラリに NumPy がリンクされているので、線形代数のパフォーマンスが" -"最適化されていない可能性があります。" +"この例ではサブパッケージを名前空間を決めるパッケージ(``myapp.plugins``)として" +"使っていますが、トップレベルのパッケージをこの(``myapp_plugins``のような)目的" +"に用いることも可能です。名前空間をどのようにして決めるかは好みの問題ですが、" +"あなたのプロジェクトのトップレベルのパッケージ(この場合では``myapp``)をプラグ" +"インの名前空間を決めるために用いると、全体の名前空間を破壊するようなプラグイ" +"ンがひとつあるだけで、あなたのプロジェクトをインポートすることができなくなる" +"のでお勧めしません。「名前空間を決めるサブパッケージ」の手法がうまく動作する" +"ためには、プラグインパッケージ側のトップレベルパッケージのディレクトリ(この場" +"合には``myapp``)に :file:`__init__.py` が存在してはいけませんし、名前空間を決" +"めるサブパッケージのディレクトリ(``myapp/plugins``)にある :file:`__init__.py`" +"をプラグインパッケージ側でインクルードしなければなりません。これはまた、 プラ" +"グインの側で:func:`setuptools.find_packages` を使うのではなく、パッケージの名" +"前を :func:`setup`の ``packages`` 引数に明示的に渡す必要がある、ということを" +"意味しています。" -#: ../source/guides/installing-scientific-packages.rst:26 +#: ../source/guides/creating-and-discovering-plugins.rst:114 msgid "" -"There are a number of alternative options for obtaining scientific Python " -"libraries (or any other Python libraries that require a compilation " -"environment to install from source and don't provide pre-built wheel files " -"on PyPI)." +"Namespace packages are a complex feature and there are several different " +"ways to create them. It's highly recommended to read the :doc:`packaging-" +"namespace-packages` documentation and clearly document which approach is " +"preferred for plugins to your project." msgstr "" -"科学分野の Python ライブラリ (または、ソースコードからインストールする際にコ" -"ンパイル環境を必要とするが、 PyPI にビルド済みの wheel ファイルが用意されてい" -"ないような、他の全ての Python ライブラリ) を手に入れるには他にも数多くの代替" -"方法があります。" +"名前空間を決めるパッケージは込み入った機能で、いくつかの異なる作成方法があり" +"ます。 :doc:`packaging-namespace-packages` 文書を読むとともに、あなたのプロ" +"ジェクト用のプラグインとしてはどちらの手法が好ましいのかを明白に文書化してお" +"くことを強くお勧めします。" -#: ../source/guides/installing-scientific-packages.rst:32 -msgid "Building from source" -msgstr "ソースコードからビルドする" +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "パッケージのメタデータを用いるやり方" -#: ../source/guides/installing-scientific-packages.rst:34 +#: ../source/guides/creating-and-discovering-plugins.rst:124 msgid "" -"The same complexity which makes it difficult to distribute NumPy (and many " -"of the projects that depend on it) as wheel files also make them difficult " -"to build from source yourself. However, for intrepid folks that are willing " -"to spend the time wrangling compilers and linkers for both C and FORTRAN, " -"building from source is always an option." +"Packages can have metadata for plugins described in the :ref:`entry-points`. " +"By specifying them, a package announces that it contains a specific kind of " +"plugin. Another package supporting this kind of plugin can use the metadata " +"to discover that plugin." msgstr "" -"NumPy (およびそれに依存するプロジェクトの多く) を wheel ファイルとして配布す" -"ることを難しくする同じ複雑さが、自分でソースコードから作成することをも困難に" -"しています。しかしながら、C言語やFORTRAN言語のコンパイラやリンカを説得するの" -"に喜んで時間を費やそうという勇敢な人々にとっては、ソースコードからビルドする" -"ことは常にひとつの選択肢です。" - -#: ../source/guides/installing-scientific-packages.rst:42 -msgid "Linux distribution packages" -msgstr "Linux 配布パッケージ" +"パッケージは、 :ref:`entry-points` に記述されたプラグインのためのメタデータを" +"持つことができます。それを指定することで、パッケージが特定の種類のプラグイン" +"を含んでいることをアナウンスします。そのメタデータを使って、同じ種類のプラグ" +"インをサポートする別のパッケージがそのプラグインを検出するのに使うことができ" +"ます。" -#: ../source/guides/installing-scientific-packages.rst:44 +#: ../source/guides/creating-and-discovering-plugins.rst:128 msgid "" -"For Linux users, the system package manager will often have pre-compiled " -"versions of various pieces of scientific software, including NumPy and other " -"parts of the scientific Python stack." +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" msgstr "" -"Linux のユーザなら、システムのパッケージマネージャを使えば NumPy やその他の科" -"学分野のPythonソフトウェア群のコンパイル済みのパッケージが準備されていること" -"も多々あります。" +"例えば、``myapp-plugin-a`` という名前のパッケージが存在して、その " +"``pyproject.toml`` に次のものを含む場合：" -#: ../source/guides/installing-scientific-packages.rst:48 +#: ../source/guides/creating-and-discovering-plugins.rst:136 msgid "" -"If using versions which may be several months old is acceptable, then this " -"is likely to be a good option (just make sure to allow access to " -"distributions installed into the system Python when using virtual " -"environments)." +"Then you can discover and load all of the registered entry points by using :" +"func:`importlib.metadata.entry_points` (or the backport_ " +"``importlib_metadata >= 3.6`` for Python 3.6-3.9):" msgstr "" -"もし数ヶ月遅れでも構わないのであれば、これは良い選択肢でしょう (仮想環境を" -"使っている場合はシステムの Python にインストールされた配布物にアクセスできる" -"ようにしておくのを忘れないでください) 。" - -#: ../source/guides/installing-scientific-packages.rst:54 -msgid "Windows installers" -msgstr "Windows 版インストーラ" +"そして、 :func:`import lib.metadata.entry_points` (あるいはPython 3.6-3.9用" +"の backport_``import lib_metadata>=3.6``)を使うことで、登録されたエントリポイ" +"ントを全て検出することができます。" -#: ../source/guides/installing-scientific-packages.rst:56 +#: ../source/guides/creating-and-discovering-plugins.rst:151 msgid "" -"Many Python projects that don't (or can't) currently publish wheel files at " -"least publish Windows installers, either on PyPI or on their project " -"download page. Using these installers allows users to avoid the need to set " -"up a suitable environment to build extensions locally." +"In this example, ``discovered_plugins`` would be a collection of type :class:" +"`importlib.metadata.EntryPoint`:" msgstr "" -"現時点で wheel ファイルを公開していない(または公開できない)多くの Python プロ" -"ジェクトでも、 PyPI 上か、または、そのプロジェクトのダウンロードページで、少" -"なくとも Windows 版インストーラを公開しています。このようなインストーラを使え" -"ば、(他言語)拡張をローカルでビルドするための適切な環境を準備する手間を省くこ" -"とができます。" +"この例では、 ``discovered_plugins`` は :class:`import lib.metadata." +"EntryPoint` 型の(オブジェクトの)集合となるでしょう。" -#: ../source/guides/installing-scientific-packages.rst:61 +#: ../source/guides/creating-and-discovering-plugins.rst:160 msgid "" -"The extensions provided in these installers are typically compatible with " -"the CPython Windows installers published on python.org." +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." msgstr "" -"このようなインストーラで用意されている(他言語)拡張は、たいてい、 python.org " -"で公開されている CPython Windows インストーラと互換性のある形で公開されていま" -"す。" +"今や、``discovered_plugins['a'].load()`` を実行することで、あなたが選んだモ" +"ジュールをインポートすることができます。" -#: ../source/guides/installing-scientific-packages.rst:64 +#: ../source/guides/creating-and-discovering-plugins.rst:163 msgid "" -"As with Linux system packages, the Windows installers will only install into " -"a system Python installation - they do not support installation in virtual " -"environments. Allowing access to distributions installed into the system " -"Python when using virtual environments is a common approach to working " -"around this limitation." +"The ``entry_point`` specification in :file:`setup.py` is fairly flexible and " +"has a lot of options. It's recommended to read over the entire section on :" +"doc:`entry points ` ." msgstr "" -"Linux のシステムパッケージの時と同じく、Windows 版インストーラはシステムワイ" -"ドの Python 環境にしかインストールしません -- つまり、仮想環境へのインストー" -"ルはサポートしていないのです。この制約を回避するよくあるやり方は、仮想環境を" -"使っている時にシステムワイドの Python 環境にインストールされた配布物へのアク" -"セスを許可することです。" +":file:`setup.py` における ``entry_points`` の指定はかなり自由度が高く、オプ" +"ションがたくさんあります。 :doc:`entry_point ` の全部のセクションに目を通すことをお勧めします。" -#: ../source/guides/installing-scientific-packages.rst:70 +#: ../source/guides/creating-and-discovering-plugins.rst:167 msgid "" -"The :term:`Wheel` project also provides a :command:`wheel convert` " -"subcommand that can convert a Windows :command:`bdist_wininst` installer to " -"a wheel." +"Since this specification is part of the :doc:`standard library `, most packaging tools other than setuptools " +"provide support for defining entry points." msgstr "" -":term:`Wheel` プロジェクトは、Windows :command:`bdist_wininst` インストーラ" -"を wheel に変換するサブコマンド :command:`wheel convert` も提供しています。" +"この仕様は :doc:`標準ライブラリ ` の一部な" +"ので、setuptools以外のほとんどのパッケージングツールでもエントリポイントを定" +"義できる機能を提供しています。" -#: ../source/guides/installing-scientific-packages.rst:77 -msgid "macOS installers and package managers" -msgstr "macOS インストーラとパッケージマネージャ" +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "パッケージングとプロジェクトの配布" -#: ../source/guides/installing-scientific-packages.rst:79 +#: ../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 "" -"Similar to the situation on Windows, many projects (including NumPy) publish " -"macOS installers that are compatible with the macOS CPython binaries " -"published on python.org." +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"introductory tutorial in :doc:`/tutorials/packaging-projects`. It still " +"assumes that you are already familiar with the contents of the :doc:`/" +"tutorials/installing-packages` page." msgstr "" -"Windows での状況と同様に、 (NumPy を含む) 多数のプロジェクトは、 python.org " -"で公開される macOS版の Python バイナリと互換性のある macOS 版インストーラを公" -"開しています。" +"この節では、 ``setuptools`` を使ったPythonパッケージの設定・パッケージング・" +"配布方法について、 :doc:`/tutorials/packaging-projects`_ の入門的なチュートリ" +"アルでは触れていないような追加的な詳細を説明します。あなたが既に :doc:`/" +"tutorials/installing-packages` ページの内容については慣れ親しんでいるものと仮" +"定して進めます。" -#: ../source/guides/installing-scientific-packages.rst:83 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" -"macOS users also have access to Linux distribution style package managers " -"such as ``Homebrew``. The SciPy site has more details on using Homebrew to " -"`install SciPy on macOS `_." +"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 "" -"macOS のユーザは、 ``Homebrew`` のような Linux ディストロスタイルのパッケージ" -"マネージャも使うことができます。ScyPy サイトには、もっと詳しい Homebrew を" -"使って `SciPy を macOS にインストールする `_ 方法の説明があります。" - -#: ../source/guides/installing-scientific-packages.rst:89 -msgid "SciPy distributions" -msgstr "SciPy 配布物" +"この節は、Pythonプロジェクトの開発についての全体的なベストプラクティスを説明" +"しているわけではありません。例えば、バージョン管理や文書化、あるいは試験につ" +"いて、手引きとなったりツールを推奨するようなことはありません。" -#: ../source/guides/installing-scientific-packages.rst:91 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" -"The SciPy site lists `several distributions `_ that provide the full SciPy stack to end users in an easy " -"to use and update format." +"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 "" -"SciPy サイトには、利用・更新が簡単なフォーマットでエンドユーザ向けの SciPy の" -"全機能を提供する `いくつかの配布物 `_ のリストがあります。" +"より詳しい参考文献としては、:ref:`setuptools` の説明文書の中の :std:doc:`パッ" +"ケージのビルドと配布 ` を挙げておきますが、推奨事" +"項のいくつかはもはや古くなっているかもしれません。喰い違いがあった場合には、" +"Python パッケージングユーザガイドの推奨事項を優先してください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "パッケージングと配布に対する要求事項" -#: ../source/guides/installing-scientific-packages.rst:96 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" -"Some of these distributions may not be compatible with the standard ``pip`` " -"and ``virtualenv`` based toolchain." +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." msgstr "" -"これらの配布物の内のいくつかは、標準的な ``pip`` や ``virtualenv`` を基礎にし" -"たツールチェーンと互換性がないかもしれません。" +"最初に、あなたが既に :ref:`パッケージをインストールする際の要求事項 " +"` を満たしていることを確実にしてください。" -#: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:808 -msgid "Spack" -msgstr "Spack" +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "\"twine\"をインストールする [1]_:" -#: ../source/guides/installing-scientific-packages.rst:101 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" -"`Spack `_ is a flexible package manager " -"designed to support multiple versions, configurations, platforms, and " -"compilers. It was built to support the needs of large supercomputing centers " -"and scientific application teams, who must often build software many " -"different ways. Spack is not limited to Python; it can install packages for " -"``C``, ``C++``, ``Fortran``, ``R``, and other languages. It is non-" -"destructive; installing a new version of one package does not break existing " -"installations, so many configurations can coexist on the same system." +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." msgstr "" -"`Spack `_ は、複数のバージョン・設定・プラッ" -"トフォーム・コンパイラをサポートできるように設計されたパッケージマネージャで" -"す。大規模スーパーコンピュータセンタや科学分野のアプリケーションチームではあ" -"るソフトウェアを異なる方法でビルドする必要が多々ありますが、そのようなニーズ" -"を満たすように作られています。Spack は Python に限らず、 ``C`` ・ ``C++`` ・ " -"``Fortran`` ・ ``R`` やその他のプログラミング言語でも利用できます。Spackは破" -"壊的ではありません; というのは、あるパッケージの新しいバージョンをインストー" -"ルしても先にインストールされたものを壊すことはなく、非常に多くの設定(でインス" -"トールされたもの)が同一システム上で共存できるのです。" +"あなたのプロジェクトの :term:`配布物 ` を :term:`PyPI " +"` にアップロードする( :ref:`後述 ` )ためにこれが必要になるでしょう。" -#: ../source/guides/installing-scientific-packages.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 +msgid "Configuring your project" +msgstr "あなたのプロジェクトを設定する" + +#: ../source/guides/distributing-packages-using-setuptools.rst:56 +msgid "Initial files" +msgstr "最初に必要なファイル群" + +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" -"Spack offers a simple but powerful syntax that allows users to specify " -"versions and configuration options concisely. Package files are written in " -"pure Python, and they are templated so that it is easy to swap compilers, " -"dependency implementations (like MPI), versions, and build options with a " -"single package file. Spack also generates *module* files so that packages " -"can be loaded and unloaded from the user's environment." +"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 "" -"Spack は、ユーザがバージョンや設定のオプションを簡潔に表現する単純で力強い文" -"法を提供します。パッケージファイルは純 Python で書かれていて、コンパイラ・ " -"(MPI のような) 依存先の実装・バージョン・ビルドオプションをひとつのパッケージ" -"ファイルの中で容易に入れ替えられるようにテンプレート化されています。Spack " -"は、また、ユーザ環境からあるパッケージをロードしたりしなかったりできるように " -"*modules* ファイルを生成します。" +"最重要のファイルは、あなたのプロジェクトのディレクトリの一番上(ルート)にあ" +"る :file:`setup.py` です。`PyPA サンプルプロジェクト `_ の `setup.py `_ に具体例がありま" +"す。" -#: ../source/guides/installing-scientific-packages.rst:119 -msgid "The conda cross-platform package manager" -msgstr "conda クロスプラットフォームパッケージマネージャ" +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr ":file:`setup.py` はふたつの主要な機能を提供します。" -#: ../source/guides/installing-scientific-packages.rst:121 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" -"`Anaconda `_ is a Python " -"distribution published by Anaconda, Inc. It is a stable collection of Open " -"Source packages for big data and scientific use. As of the 5.0 release of " -"Anaconda, about 200 packages are installed by default, and a total of " -"400-500 can be installed and updated from the Anaconda repository." +"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()`` " +"function. The keyword arguments to this function are how specific details " +"of your project are defined. The most relevant arguments are explained in :" +"ref:`the section below `." msgstr "" -"`Anaconda `_ は Anaconda 社が" -"公開した Python 配布物です。Anaconda は、ビッグデータや科学分野で使用する一連" -"のオープンソースソフトウェアの安定版を集めたものです。Anaconda のバージョン " -"5.0 では、デフォルトで約 200 のパッケージがインストールされていて、全部で " -"400-500 が Anaconda リポジトリからインストール可能です。" +"まず、あなたのプロジェクトをさまざまな角度から設定するためのファイルです。 :" +"file:`setup.py` の主要な機能は、グローバルな ``setup()`` 関数を含んでいること" +"です。この関数にキーワード引数を渡すことで、あなたのプロジェクトの特定の細部" +"を定義することができます。適切な引数のほとんどについて :ref:`次節 ` で説明します。" -#: ../source/guides/installing-scientific-packages.rst:127 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" -"``conda`` is an open source (BSD licensed) package management system and " -"environment management system included in Anaconda that allows users to " -"install multiple versions of binary software packages and their " -"dependencies, and easily switch between them. It is a cross-platform tool " -"working on Windows, macOS, and Linux. Conda can be used to package up and " -"distribute all kinds of packages, it is not limited to just Python packages. " -"It has full support for native virtual environments. Conda makes " -"environments first-class citizens, making it easy to create independent " -"environments even for C libraries. It is written in Python, but is Python-" -"agnostic. Conda manages Python itself as a package, so that :command:`conda " -"update python` is possible, in contrast to pip, which only manages Python " -"packages. Conda is available in Anaconda and Miniconda (an easy-to-install " -"download with just Python and conda)." +"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 "" -"``conda`` は、複数のバージョンのソフトウェアのバイナリパッケージやその依存先" -"パッケージをインストールして容易に切り替えて使えるようにする Anaconda に含ま" -"れる (BSDライセンスの) オープンソースのパッケージマネジメントシステム兼環境管" -"理システムです。(これは) Windows・MacOS・Linuxで動作するクロスプラットフォー" -"ムのツールです。conda を使えば、Python のパッケージに限らず、あらゆる種類の" -"パッケージをまとめたり配布したりできます。Python に組み込まれた仮想環境を完全" -"にサポートしています。 C 言語で書かれたライブラリさえも容易に独立した環境を生" -"成できるようにすることで、conda は(仮想)環境を制限なく使えるもの(第１級オブ" -"ジェクト)にしています。Python で書かれていていますが、Pythonに依存しているわ" -"けではありません。conda は Python そのものをパッケージのひとつとして扱うた" -"め :command:`conda update python` とすることが可能で、Python のパッケージだけ" -"を扱う pip とは対照的です。conda は Anaconda や Miniconda (Python と conda が" -"動作するだけの最小版のAnacoda) から手に入ります。" +"それは、パッケージングする上での作業項目に関連したさまざまなコマンドを走らせ" +"るためのコマンドラインインタフェイスです。使用可能なコマンドを一覧するには、 " +"``python setup.py --help-commands`` を実行してください。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:2 -msgid "Installing stand alone command line tools" -msgstr "スタンドアローンのコマンドラインツールをインストールする" +#: ../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` は :file:`setup.py` のコマンド群に対するオプションの既定値" +"を含む初期化ファイルです。 `PyPA サンプルプロジェクト `_ の中の `setup.cfg `_ に使" +"用例が出ています。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +#: ../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:91 msgid "" -"Many packages provide command line applications. Examples of such packages " -"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ with an \"rst\" extension, although this is not a " +"requirement; multiple variants of `Markdown `_ are supported as well (look at ``setup()``'s :ref:" +"`long_description_content_type ` argument)." msgstr "" -"多くのパッケージは、コマンドラインアプリケーションを提供しています。そのよう" -"なパッケージの例としては、 `mypy `_ ・ " -"`flake8 `_ ・ `black `_ ・ :ref:`pipenv` が挙げられます。" +"すべてのプロジェクトは、プロジェクトのゴールを記したreadmeファイルを備えるべ" +"きです。一番良くあるフォーマットは拡張子が \"rst\" の `reStructuredText " +"`_ ですが、これは(訳註、必須の)要求" +"事項というわけではありません。他にも複数の種類の `マークダウン `_ フォーマットがサポートされています" +"(``setup()`` の :ref:`long_description_content_type ` 引数を見て" +"ください)。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:10 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" -"Usually you want to be able to access these applications from anywhere on " -"your system, but installing packages and their dependencies to the same " -"global environment can cause version conflicts and break dependencies the " -"operating system has on Python packages." +"For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -"通常ならシステムのどこからでもこれらのアプリケーションにアクセスできるように" -"したいと思うでしょうが、パッケージとその依存先パッケージを同じグローバル環境" -"にインストールすると、バージョンの衝突を起こしてオペレーティングシステムが" -"持っている Python パッケージ間の依存関係を破壊してしまうかもしれません。" +"`PyPA sample project `_ の中の " +"`README.md `_ に例" +"が出ています。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:15 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" -":ref:`pipx` solves this by creating a virtual environment for each package, " -"while also ensuring that its applications are accessible through a directory " -"that is on your ``$PATH``. This allows each package to be upgraded or " -"uninstalled without causing conflicts with other packages, and allows you to " -"safely run the applications from anywhere." +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" +"`README.rst`, :file:`README.txt`, or :file:`README`) included in source " +"distributions by default. The built-in :ref:`distutils` library adopts this " +"behavior beginning in Python 3.7. Additionally, :ref:`setuptools` 36.4.0+ " +"will include a :file:`README.md` if found. If you are using setuptools, you " +"don't need to list your readme file in :file:`MANIFEST.in`. Otherwise, " +"include it to be explicit." msgstr "" -":ref:`pipx` は、 ``$PATH`` に含まれるディレクトリを通してアプリケーションにア" -"クセスできるようにしつつ各パッケージに仮想環境を作成することでこの問題を解決" -"します。こうすることで、各パッケージの更新や削除をしても他のパッケージには影" -"響を与えず、どこからでもアプリケーションを安全に走らせることができるようにで" -"きます。" +":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/installing-stand-alone-command-line-tools.rst:21 -msgid "pipx only works with Python 3.6+." -msgstr "pipx は Python 3.6+ でのみ動作します。" +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 -msgid "pipx is installed with pip:" -msgstr "pipx は pip と一緒にインストールされています:" +#: ../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:`MANIFEST.in の使い方 `」を見てください。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:41 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" -"``ensurepath`` ensures that the application directory is on your ``$PATH``. " -"You may need to restart your terminal for this update to take effect." +"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 "" -"``ensurepath `` は、アプリケーションのあるディレクトリが ``$PATH`` に含まれる" -"ようにすることを保証します。この更新(訳注、``$PATH``の修正のこと)が効果を持つ" -"ようにするためにターミナルを再起動する必要があるかもしれません。" +"しかしながら、あなたは必ずしも :file:`MANIFEST.in` を使わなくても構いません。" +"一つの例として`PyPA サンプルプロジェクト `_ では、必要なファイルがすべて 43.0.0およびこれ以降の:ref:" +"`setuptools`に含まれているので、マニフェストファイルを削除しています。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:44 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" -"Now you can install packages with ``pipx install`` and run the package's " -"applications(s) from anywhere." +":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -"これで、 ``pipx install`` を使ってパッケージをインストールすることができるよ" -"うになり、どこからでもそのパッケージのアプリケーションを起動することができる" -"ようになりました。" +":file:`MANIFEST.in` は、wheelなどのバイナリ配布物には影響を与えません。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:52 -#: ../source/specifications/entry-points.rst:114 -msgid "For example:" -msgstr "例:" +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "LICENSE.txt" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:74 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" -"To see a list of packages installed with pipx and which applications are " -"available, use ``pipx list``:" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"can not be legally used or distributed by anyone other than the copyright " +"holder. If you're unsure which license to choose, you can use resources such " +"as `GitHub's Choose a License `_ or consult a " +"lawyer." msgstr "" -"pipx でインストールされたパッケージのリストやどんなアプリケーションが使用可能" -"かを見るためには、 ``pipx list`` を使ってください:" +"各パッケージは、配布の条件を指定するライセンスファイルを含んでいるべきです。" +"多くの司法管轄区域(訳註、大雑把にいうと「多くの国」)では、明示的なライセンス" +"条項がないと、著作権保持者でなければ誰も適法にパッケージを使用したり配布した" +"りすることができません。どのライセンスを選択すればよいか分からない場合には、" +"`GitHubの「オープンソースライセンスを選ぶには」 `_ などのリソースを見ることも、弁護士に相談することもできます。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:95 -#: ../source/guides/installing-stand-alone-command-line-tools.rst:98 -msgid "To upgrade or uninstall a package:" -msgstr "パッケージを更新またはアンインストールするには:" +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" +"`PyPAサンプルプロジェクト `_ の " +"`LICENSE.txt `_ に例がでています。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:102 -#: ../source/guides/installing-stand-alone-command-line-tools.rst:105 -msgid "pipx can be upgraded or uninstalled with pip:" -msgstr "pipx は pip を使って更新やアンインストールができます:" +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "<あなたのパッケージ>" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:118 -#: ../source/guides/installing-stand-alone-command-line-tools.rst:121 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" -"pipx also allows you to install and run the latest version of an application " -"in a temporary, ephemeral environment. For example:" +"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 "" -"また、pipx ならアプリケーションの最新版を一時的で短命の環境にインストールして" -"動作させることができます。例えば:" +"必ずそうしなければならないというわけではありませんが、あなたのプロジェクトと" +"同じか非常に近い :ref:`名前 ` の単一のプロジェクトをPythonのモ" +"ジュールやパッケージのトップレベルに配置するということが共通の慣習になってい" +"ます。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:125 -#: ../source/guides/installing-stand-alone-command-line-tools.rst:128 -msgid "To see the full list of commands pipx offers, run:" +#: ../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 "" -"pipx で使える(サブ)コマンドの完全なリストを見たければ、次のようにしてくださ" -"い:" +"`PyPAサンプルプロジェクト `_ に含まれ" +"る `サンプル `_ " +"パッケージに例が出ています。" -#: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -#: ../source/guides/installing-stand-alone-command-line-tools.rst:134 -msgid "You can learn more about pipx at https://pipx.pypa.io/." -msgstr "pipx については、 https://pipx.pypa.io/ でもっと学べます。" +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "setup() の引数" -#: ../source/guides/installing-using-linux-tools.rst:5 -msgid "Installing pip/setuptools/wheel with Linux Package Managers" +#: ../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 "" -"Linux パッケージマネージャを使って pip/setuptools/wheel をインストールする" - -#: ../source/guides/installing-using-linux-tools.rst:8 -msgid "2021-07-26" -msgstr "2021-07-26" +"上述の通り、:file:`setup.py` の第一の機能は、グローバルスコープの " +"``setup()`` 関数を含むことです。この関数に与えるキーワード引数は、あなたのプ" +"ロジェクトの特定の細部がどのように定義されているかを示すものです。" -#: ../source/guides/installing-using-linux-tools.rst:10 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This section covers how to install :ref:`pip`, :ref:`setuptools`, and :ref:" -"`wheel` using Linux package managers." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -"この節では、Linux のパッケージマネージャを使って :ref:`pip` ・ :ref:" -"`setuptools` ・ :ref:`wheel` をインストールする方法について説明します。" +"いくつかについては、情報がどこか他の場所に移されるまでの一時的な説明が以下に" +"あります。すべてを列挙したものは :doc:`setuptools の説明文書 ` で見つかるでしょう。" -#: ../source/guides/installing-using-linux-tools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"If you're using a Python that was downloaded from `python.org `_, then this section does not apply. See the :ref:" -"`installing_requirements` section instead." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -"`python.org `_ からダウンロードした Python を使ってい" -"るなら、この節の議論はあてはまりません。代わりに :ref:" -"`installing_requirements` 節を見てください。" +"ほとんどのソースコード断片(スニペット)は、`PyPA サンプルプロジェクト " +"`_ の中の `setup.py `_ から取られたものです。" -#: ../source/guides/installing-using-linux-tools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" -"Note that it's common for the versions of :ref:`pip`, :ref:`setuptools`, " -"and :ref:`wheel` supported by a specific Linux Distribution to be outdated " -"by the time it's released to the public, and updates generally only occur " -"for security reasons, not for feature updates. For certain Distributions, " -"there are additional repositories that can be enabled to provide newer " -"versions. The repositories we know about are explained below." +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." msgstr "" -"特定の Linux ディストロでサポートされているバージョンの :ref:`pip` ・ :ref:" -"`setuptools` ・ :ref:`wheel` が公開時点で既に旧バージョンになってしまっている" -"のに、更新されるのはセキュリティが理由の時だけで機能追加があっても更新されな" -"い、というのはよくあることです。ディストロの中にはより新しいバージョンを提供" -"することができる追加のリポジトリが存在する場合もあります。以下では、そのよう" -"なリポジトリのうちの既知のものを説明します。" +"あなたのユーザへ互換性情報を伝える方法としてバージョン番号を使うやり方につい" +"ては、 :ref:`バージョンをつける規則を選択するには ` をご覧ください。" -#: ../source/guides/installing-using-linux-tools.rst:24 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "``packages``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" -"Also note that it's somewhat common for Distributions to apply patches for " -"the sake of security and normalization to their own standards. In some " -"cases, this can lead to bugs or unexpected behaviors that vary from the " -"original unpatched versions. When this is known, we will make note of it " -"below." +"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/installing-using-linux-tools.rst:31 -msgid "Fedora" -msgstr "Fedora" +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +msgstr "``py_modules``" -#: ../source/guides/installing-using-linux-tools.rst:37 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" -"To learn more about Python in Fedora, please visit the `official Fedora " -"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +"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 "" -"Fedora における Python についてもっと学ぶには、 `official Fedora docs`_ ・ " -"`Python Classroom`_ ・ `Fedora Loves Python`_ を見てください。" +"あなたのプロジェクトに、プロジェクトの一部ではない単一ファイルのPythonモ" +"ジュールがあるなら、 :ref:`setuptools` に知らせるために、そのようなモジュール" +"の(拡張子``.py``を削除した)名前を ``py_modules`` に列挙してください。" -#: ../source/guides/installing-using-linux-tools.rst:45 -msgid "CentOS/RHEL" -msgstr "CentOS/RHEL" +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" -#: ../source/guides/installing-using-linux-tools.rst:47 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" -"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " -"repositories, although :ref:`setuptools` is installed by default." +"\"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 "" -"CentOS と RHEL は、そのコアリポジトリでは :ref:`pip` や :ref:`wheel` を提供し" -"ていませんが、 :ref:`setuptools` はデフォルトでインストールされます。" +"``install_requires`` は、プロジェクトが動作するために最低限必要な依存関係を指" +"定するのに使われます。プロジェクトが :ref:`pip` でインストールされる場合に" +"は、この指定を見て依存関係(訳註、にある他パッケージ)をインストールするために" +"用いられます。" -#: ../source/guides/installing-using-linux-tools.rst:50 -msgid "To install pip and wheel for the system Python, there are two options:" +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." msgstr "" -"システムに付属の Python 用に pip や wheel をインストールするには、二つのやり" -"方があります:" +"さらなる ``install_requires`` の使い方については :ref:`install_requires対" +"Requirementsファイル ` を参照してくだ" +"さい。" -#: ../source/guides/installing-using-linux-tools.rst:52 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" -"Enable the `EPEL repository `_ using " -"`these instructions `__. On EPEL 7, you can install pip and " -"wheel like so:" +"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 "" -"`これらの指示 `__ に従って `EPEL リポジトリ `_ を有効にしてください。 EPEL 7 では、pip と " -"wheel をこんなふうにインストールできます:" +"追加のファイルを :term:`パッケージ ` にインストールする必要が" +"ある、というのはよくあることです。このようなファイルは、しばしば、そのパッ" +"ケージの実装に深く関係していたり、パッケージを利用するプログラマの利益になる" +"ような説明を含んだテキストファイルであったりします。このようなファイルは" +"「パッケージデータ」と呼ばれます。" -#: ../source/guides/installing-using-linux-tools.rst:61 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" -"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " -"setuptools, since it's in the core repository." +"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 "" -"EPEL はシステムに欠けていて衝突しないパッケージだけを提供しているので、コアリ" -"ポジトリに入っている setuptools は EPEL にはありません。" +"この引数に渡す値は、パッケージ名から、そのパッケージ内にコピーされるべきファ" +"イルの相対パス名を列挙したもののマッピングになっていなければなりません。パス" +"名はパッケージを含むディレクトリからの相対パスとして解釈されます。" -#: ../source/guides/installing-using-linux-tools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" -"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " -"wheel like so:" +"For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -"`これらの指示 `__ [1]_ に従って `PyPA Copr Repo `_ を有効にしてください。 pip と wheel はこうやってイン" -"ストールできます:" +"詳しくは、 :std:doc:`setuptools説明文書 ` の中の :std:doc:`" +"データファイルを追加するには <1setuptools:userguide/datafiles>` を見てくださ" +"い。" -#: ../source/guides/installing-using-linux-tools.rst:74 -msgid "To additionally upgrade setuptools, run:" -msgstr "さらに setuptools を更新するには、次のようにしてください:" +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "``data_files``" -#: ../source/guides/installing-using-linux-tools.rst:81 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" -"To install pip, wheel, and setuptools, in a parallel, non-system environment " -"(using yum) then there are two options:" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of your :term:" +"`packages `. The ``data_files`` directive allows you to do " +"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 "" -"システムの環境とは別に (yum を使って) pip ・ wheel ・ setuptools をインストー" -"ルするには、ふたつのやり方があります:" +":ref:`パッケージデータ ` を設定すればほとんどの需要に応えられま" +"すが、あなたの :term:`パッケージ ` の *外側* にデータファイル" +"を置きたいこともあるでしょう。 ``data_files`` ディレクティブでそれができま" +"す。大抵は、Pythonのパッケージを認識しないような他のプログラムから利用する" +"ファイルをインストールする必要がある時に、これが役に立つでしょう。" -#: ../source/guides/installing-using-linux-tools.rst:85 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" -"Use the \"Software Collections\" feature to enable a parallel collection " -"that includes pip, setuptools, and wheel." +"Each ``(directory, files)`` pair in the sequence specifies the installation " +"directory and the files to install there. The ``directory`` must be a " +"relative path (although this may change in the future, see `wheel Issue #92 " +"`_), and it is interpreted relative " +"to the installation prefix (Python’s ``sys.prefix`` for a default " +"installation; ``site.USER_BASE`` for a user installation). Each file name in " +"``files`` is interpreted relative to the :file:`setup.py` script at the top " +"of the project source distribution." msgstr "" -"pip ・ setuptools ・ wheel を含むコレクションを (システムとは) 並行に有効化し" -"て \"ソフトウェアコレクション\" 機能を使ってください。" +"設定値の中の ``(ディレクトリ, ファイル)`` の組は、それぞれインストール先の" +"ディレクトリとそこにインストールされるべきファイル(群)を指定しています。 ``" +"ディレクトリ `` は相対パスでなければならず (これは将来変更されるか" +"もしれません。 `wheel Issue #92 `_ " +"を見てください)、インストール先プレフィクス(デフォルトではPythonの ``sys." +"prefix``、ないし、ユーザインストールでは ``site.USER_BASE`` )に対する相対パス" +"として解釈されます。 ``files`` 内のファイル名は、プロジェクトのソースコード配" +"布物の最上位にある :file:`setup.py` スクリプトに対する相対パスとして解釈され" +"ます。" -#: ../source/guides/installing-using-linux-tools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" -"For Redhat, see here: https://developers.redhat.com/products/" -"softwarecollections/overview" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." msgstr "" -"Red Hat についてはこちらを見てください: https://developers.redhat.com/" -"products/softwarecollections/overview" +"さらに詳しくは、 :ref:`追加的なファイルをインストールするには ` の中のdistutilsの節を見てください。" -#: ../source/guides/installing-using-linux-tools.rst:90 -msgid "For CentOS, see here: https://github.com/sclorg" -msgstr "CentOS の場合は、こちらを見てください: https://github.com/sclorg" +#: ../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 "" +"パッケージをeggとしてインストールする時には、 ``data_files`` はサポートされて" +"いません。だから、もしあなたのプロジェクトで :ref:`setuptools` を使っているな" +"らば ``pip`` でインストールしなければなりません。あるいは、 ``--old-and-" +"unmanageable`` オプション付きの ``python setup.py`` を使わなければなりませ" +"ん。" -#: ../source/guides/installing-using-linux-tools.rst:92 -msgid "Be aware that collections may not contain the most recent versions." +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``scripts``" msgstr "" -"コレクションに含まれているバージョンが最新版であるとは限らない点に注意してく" -"ださい。" -#: ../source/guides/installing-using-linux-tools.rst:94 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" -"Enable the `IUS repository `_ and install one of the " -"`parallel-installable `_ " -"Pythons, along with pip, setuptools, and wheel, which are kept fairly up to " -"date." +"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 "" -"`IUS リポジトリ `_ を有効にして、かなり最新版に近い状態" -"に維持されている pip ・ setuptools ・ wheel と一緒に `並列インストール可能 " -"`_ な Python の内のひとつ" -"をインストールしてください。" +"``setup()`` はあらかじめ作成されたスクリプトをインストールするために :ref:" +"`scripts ` キーワードをサポートして" +"いますが、異機種間の互換性を取るためのアプローチとして推奨されるのは :ref:" +"`console_scripts` エントリーポイント(後述)を使うことです。" -#: ../source/guides/installing-using-linux-tools.rst:100 -msgid "For example, for Python 3.4 on CentOS7/RHEL7:" -msgstr "例えば、CentOS7/RHEL7 での Python 3.4 については:" +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "バージョン体系を選択する" -#: ../source/guides/installing-using-linux-tools.rst:108 -msgid "openSUSE" -msgstr "openSUSE" +#: ../source/guides/distributing-packages-using-setuptools.rst:293 +msgid "" +"See :ref:`versioning` for information on common version schemes and how to " +"choose between them." +msgstr "" +"よくあるバージョンを指定する枠組みにどんなものがあるかや、その中からひとつの" +"枠組みを選択する方法については、 :ref:`バージョニング ` を見てく" +"ださい。" -#: ../source/guides/installing-using-linux-tools.rst:118 -msgid "Debian/Ubuntu and derivatives" -msgstr "Debian/Ubuntu とその派生物" +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "開発モードで作業する" -#: ../source/guides/installing-using-linux-tools.rst:120 -msgid "Firstly, update and refresh repository lists by running this command:" +#: ../source/guides/distributing-packages-using-setuptools.rst:300 +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 " +"without reinstallation: changes to Python source files in projects installed " +"as editable will be reflected the next time an interpreter process is " +"started." msgstr "" -"第一に、このコマンドを実行してリポジトリリストを更新し情報を新しくしてくださ" -"い。" +"あなたがまだ作業している途中なら、プロジェクトを「編集可能」または「開発」" +"モードでインストールすることができます。編集可能な状態でインストールされる" +"と、再インストールしなくてもプロジェクトをその場で編集することができます: 編" +"集可能状態でインストールされたプロジェクトのPythonソースコードに変更を加える" +"と、次にインタープリターのプロセスが開始された時に反映されます。" -#: ../source/guides/installing-using-linux-tools.rst:129 +#: ../source/guides/distributing-packages-using-setuptools.rst:306 msgid "" -"Recent Debian/Ubuntu versions have modified pip to use the `\"User Scheme\" " -"`_ by default, " -"which is a significant behavior change that can be surprising to some users." +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" msgstr "" -"最近のバージョンの Debian/Ubuntu は、 pip がデフォルトで `\"User Scheme\" " -"`_ を使うように修正" -"されていますが、これはユーザの一部を驚かせるような重要な動作の変更に当たるで" -"しょう。" - -#: ../source/guides/installing-using-linux-tools.rst:135 -msgid "Arch Linux" -msgstr "Arch Linux" +"Pythonのパッケージを「編集可能」/「開発」モードでインストールするには、そのプ" +"ロジェクトのルートディレクトリへ移動して、次のコマンドを走らせてください:" -#: ../source/guides/installing-using-linux-tools.rst:143 +#: ../source/guides/distributing-packages-using-setuptools.rst:314 msgid "" -"Currently, there is no \"copr\" yum plugin available for CentOS/RHEL, so the " -"only option is to manually place the repo files as described." +"The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " +"refers to the current working directory, so together, it means to install " +"the current directory (i.e. your project) in editable mode. This will also " +"install any dependencies declared with ``install_requires`` and any scripts " +"declared with ``console_scripts``. Dependencies will be installed in the " +"usual, non-editable mode." msgstr "" -"現時点では、 CentOS/RHEL には yum プラグインの \"copr\" が存在しないので、後" -"述するように手動でリポジトリファイルを配置するしかありません。" - -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 -msgid "Install packages in a virtual environment using pip and venv" -msgstr "pip と venv を使って仮想環境にパッケージをインストールする" +"pip のコマンドラインオプションの ``-e`` は ``--editable`` の省略形で、 ``.`` " +"は現在作業をしているディレクトリのことですので、まとめると「現在のディレクト" +"リ(つまりあなたのプロジェクト)に編集可能モードでインストールせよ」ということ" +"になります。また、このコマンドによって ``install_requires`` に宣言された依存" +"先のパッケージや ``console_scripts`` に書かれたスクリプトもインストールされま" +"す。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +#: ../source/guides/distributing-packages-using-setuptools.rst:321 msgid "" -"This guide discusses how to create and activate a virtual environment using " -"the standard library's virtual environment tool :ref:`venv` and install " -"packages. The guide covers how to:" +"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 "" -"このガイド文書では、標準ライブラリの仮想環境ツール :ref:`venv` を使って仮想環" -"境を作成し活性化する方法と、パッケージをインストールする方法について議論しま" -"す。このガイド文書は次のようなことを行う方法をカバーします:" - -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:8 -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:153 -msgid "Prepare pip" -msgstr "pip の準備をする" +"依存先のプロジェクトも同様に編集可能モードでインストールしたい時があるかもし" +"れません。例えば、あなたのプロジェクトが \"foo\" と \"bar\" というパッケージ" +"を要求していて、 \"bar\" についてはVCS (バージョンコントロールシステム) から" +"編集可能モードでインストールしたい場合には、requirements ファイルを次のように" +"構成すれば良いでしょう::" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 -msgid "Install packages into a virtual environment using the ``pip`` command" -msgstr "``pip`` コマンドを使って仮想環境にパッケージをインストールする" +#: ../source/guides/distributing-packages-using-setuptools.rst:329 +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\" についてPyPIではなくVCSから充当するようにと依存関" +"係を上書きしています。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 -msgid "Use and create a requirements file" -msgstr "requirements ファイルを使う、作成する" +#: ../source/guides/distributing-packages-using-setuptools.rst:333 +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 "" +"そうではなくて、 \"bar\" をローカルディレクトリから編集可能モードでインストー" +"ルしたい場合には、 requirements ファイルの先頭にローカルのディレクトリパスを" +"置いて次のようになるでしょう::" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +#: ../source/guides/distributing-packages-using-setuptools.rst:338 msgid "" -"This guide applies to supported versions of Python, currently 3.8 and higher." +"Otherwise, the dependency will be fulfilled from PyPI, due to the " +"installation order of the requirements file. For more on requirements " +"files, see the :ref:`Requirements File ` section in " +"the pip docs. For more on VCS installs, see the :ref:`VCS Support ` section of the pip docs." msgstr "" -"このガイド文書は、サポートされている Python のバージョン、現時点では 3.8 およ" -"びこれ以降のものに適用されます。" +"さもなければ requirements ファイルに書かれた順にインストールされてしまうの" +"で、依存先のパッケージが PyPI から充当されてしまいます。 requirements ファイ" +"ルについてさらに詳しく知りたい場合は、 pipの解説文書の :ref:`Requirements " +"ファイル ` の節を見てください。VCSからのインストール" +"については、同書の :ref:`VCSサポート ` の節を見てください。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +#: ../source/guides/distributing-packages-using-setuptools.rst:342 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." +"Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -"この文書では、 **パッケージ** という用語を通常は外部のホストからインストール" -"される :term:`配布パッケージ ` の意味で使います。これ" -"は Python ソースコードでモジュールをインポートするという意味で使われる :term:" -"`インポートパッケージ ` とは異なります。" +"最後に、もし依存先パッケージは何もインストールしたくないのであれば、このよう" +"にします:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:349 msgid "" -"This guide has the prerequisite that you are using an official Python " -"version obtained from . If you are using " -"your operating system's package manager to install Python, please ensure " -"that Python is installed before proceeding with these steps." +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -"このガイド文書は、 から取得する公式の " -"Python を使っていることを前提条件にしています。Python をインストールするのに" -"オペレーティングシステムのパッケージマネージャを使っているのであれば、ここに" -"述べるようなステップを進める前に、Python がインストールされていることを確実に" -"してください。" - -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:32 -msgid "Create and Use Virtual Environments" -msgstr "仮想環境を構築し使用する" +"さらに詳しいことを知りたい場合は、 :ref:`setuptools` 文書の :doc:`開発モード " +"` の 節を見てください。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:35 -msgid "Create a new virtual environment" -msgstr "新しい仮想環境を作成する" +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "プロジェクトをパッケージングする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:37 +#: ../source/guides/distributing-packages-using-setuptools.rst:358 msgid "" -":ref:`venv` (for Python 3) allows you to manage separate package " -"installations for different projects. It creates a \"virtual\" isolated " -"Python installation. When you switch projects, you can create a new virtual " -"environment which is isolated from other virtual environments. You benefit " -"from the virtual environment since packages can be installed confidently and " -"will not interfere with another project's environment." +"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 "" -":ref:`venv` (Python 3 用) を使うと、異なるプロジェクトにそれぞれ別のパッケー" -"ジをインストールして管理できます。(仮想環境は) 互いに影響を与えない\"仮想的な" -"\" Python インストール環境を生成します。別のプロジェクトに移動すると、他の仮" -"想環境から隔離された新しい仮想環境を作成することができます。仮想環境を使うこ" -"とで、パッケージ群を自信を持ってインストールすることができ、他のプロジェクト" -"の環境には干渉しないであろうことから、あなたは利益を得ることができます。" +"あなたのプロジェクトを :term:`PyPI ` のような :" +"term:`パッケージインデックス ` からインストールできるようにす" +"るには、 :term:`配布物 ` (:term:`パッケージ " +"`の名前でも知られる) を作成しなければならないでしょう。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:45 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" -"It is recommended to use a virtual environment when working with third party " -"packages." -msgstr "第三者のパッケージ群を使う時には仮想環境を用いることが推奨されます。" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" +"あなたのプロジェクトでwheelsやsdistsをビルドする前に、 ``build`` パッケージを" +"インストールする必要があります。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "ソースコード配布物" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 msgid "" -"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``:" +"Minimally, you should create a :term:`Source Distribution `:" msgstr "" -"仮想環境を作成するには、プロジェクトのディレクトリへ行って次のようなコマンド" -"を実行してください。これによって、ローカルの ``.venv`` フォルダに新しい仮想環" -"境ができるでしょう:" +"少なくとも、 :term:`ソースコード配布物 ` " +"を作成するべきです:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +#: ../source/guides/distributing-packages-using-setuptools.rst:398 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``." +"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 " +"the distribution is pure Python (i.e. contains no extensions), it still " +"involves a build step to build out the installation metadata from :file:" +"`setup.py` and/or :file:`setup.cfg`." msgstr "" -"二つ目の引数は、仮想環境を作成するべき場所の指定です。一般的には、プロジェク" -"トのルートディレクトリに ``.venv`` という名前で作成します。" +"ソースコード配布物はビルドされていない (すなわち、 :term:`ビルド済み配布物 " +"` ではない) ので、pip でインストールする際にビルドする段" +"階が必要になります。配布物が純Python (つまり (訳注、多言語で書かれた) 拡張を" +"含まない) であったとしても、 :file:`setup.py` や :file:`setup.cfg` からインス" +"トール用メタデータを取り出してビルドする段階を必要とするのです。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "Wheels" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 msgid "" -"``venv`` will create a virtual Python installation in the ``.venv`` folder." +"You should also create a wheel for your project. A wheel is a :term:`built " +"package ` that can be installed without needing to go " +"through the \"build\" process. Installing wheels is substantially faster for " +"the end user than installing from a source distribution." msgstr "" -"``venv`` は仮想的な Python を ``.venv`` ディレクトリの中にインストールするで" -"しょう。" +"あなたのプロジェクトでは、wheelも作成するべきです。wheel は、インストールする" +"のにビルド処理を行う必要がない :term:`ビルド済み配布物 ` " +"です。wheelを使えば、ソースコード配布物からのインストールに比べてエンドユーザ" +"にとって相当素早くインストールすることができます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" -"You should exclude your virtual environment directory from your version " -"control system using ``.gitignore`` or similar." +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." msgstr "" -"仮想環境のディレクトリは、 ``.gitignore`` やその類似物を使ってバージョン管理" -"システムから除外しておくべきです。" - -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 -msgid "Activate a virtual environment" -msgstr "仮想環境を活性化する" +"あなたのプロジェクトが純Pythonなら、きっとあなたは:ref:`\"純Pythonの" +"Wheel\" (後述) `を作成することになるでしょう。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +#: ../source/guides/distributing-packages-using-setuptools.rst:416 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``." +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -"仮想環境に (依存先の) パッケージをインストールして使用できるようにするには、" -"まず *仮想環境* を ``activate`` しなければなりません。仮想環境を活性化する" -"と、その仮想環境に特有の ``python`` と ``pip`` の実行ファイルがシェルの " -"``PATH`` 変数に追加されます。" +"もしあなたのプロジェクトにコンパイル済の拡張が含まれているなら、 :ref:`*プ" +"ラットフォーム Wheel* (後述) ` を作成することになるでしょ" +"う。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" -"To confirm the virtual environment is activated, check the location of your " -"Python interpreter:" +"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 "" -"仮想環境が activate されたことを確認するには、 Python インタープリタの場所を" -"確かめましょう:" +"あなたのプロジェクトが Python 2をさぽーとしていて、かつ、C言語拡張を含むので" +"あれば、次のものをあなたの :file:`setup.cfg` ファイルに追加して *ユニバーサ" +"ル Wheel* と呼ばれるものを作成するべきです:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:428 msgid "" -"While the virtual environment is active, the above command will output a " -"filepath that includes the ``.venv`` directory, by ending with the following:" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." msgstr "" -"仮想環境が active である間は、上記のコマンドは ``.venv`` ディレクトリを含む" -"ファイルパスを出力することでしょう、つまり以下のようになって終了します:" +"あなたのプロジェクトにC言語拡張がなく、かつ、Python 2 および3をサポートしてい" +"る場合に限って、この設定を使ってください。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "純Python Wheels" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 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." +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." msgstr "" -"仮想環境が active である間は、pip はパッケージをその仮想環境内にインストール" -"します。これによって、あなたの Python アプリケーションからそのパッケージをイ" -"ンポートして使用することができるようになります。" +"*純Python Wheels* は、コンパイル済拡張を含んでおらず、従って単独のPython " +"wheelを要求するだけです。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 -msgid "Deactivate a virtual environment" -msgstr "仮想環境を非活性化 する" +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "wheelをビルドするには:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +#: ../source/guides/distributing-packages-using-setuptools.rst:454 msgid "" -"If you want to switch projects or leave your virtual environment, " -"``deactivate`` the environment:" +"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 "" -"プロジェクトを切り替えたい、あるいは、仮想環境から離脱したい時は、仮想環境を " -"``deactivate`` してください:" +"``wheel`` パッケージは、ソースコードが純Pythonであることを検出して、Python 3 " +"へのインストールであればどこでも使えるのでそのように名付けられたwheelをビルド" +"します。wheelファイルの名称について詳しいことは :pep:`425` を見てください。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +#: ../source/guides/distributing-packages-using-setuptools.rst:458 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." +"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 "" -"シェルを終了すれば、仮想環境を非活性化 することになるでしょう。" -"もし、新しいシェル窓を開いて、そこで仮想環境を使いたい時は、再活性化 " -" してください。" +"``--wheel`` か ``--sdist`` を付けずに ``build`` を実行すると、両方のファイル" +"が作成されます; 複数のwheelファイルにしたくないときにはこれが便利です。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 -msgid "Reactivate a virtual environment" -msgstr "仮想環境を再活性化 する" +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "プラットフォームWheels" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +#: ../source/guides/distributing-packages-using-setuptools.rst:466 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." +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -"既存の仮想環境を活性化 したい場合は、仮想環境の活性化に関する上述" -"のやり方に従ってください。新しい仮想環境を作成する必要はありません。" +"*プラットフォームWheels* は、LinuxやmacOSあるいはWindowsのような特定のプラッ" +"トフォーム向けのwheelで、大抵の場合は(訳注、特定のプラットフォーム向けにコン" +"パイルされた)コンパイル済み拡張を含むためです。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +#: ../source/guides/distributing-packages-using-setuptools.rst:484 msgid "" -":ref:`pip` is the reference Python package manager. It's used to install and " -"update packages into a virtual environment." +"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 "" -":ref:`pip` は Python の参照モデルとなるパッケージマネージャです。仮想環境内で" -"パッケージのインストールや更新に用いられます。" +"``wheel`` パッケージは、ソースコードが純Pythonで書かれていないと判断すると、" +"ビルドされたプラットフォーム上でのみ利用可能であるように命名されたwheelを作成" +"します。wheelファイルの命名規則については、 :pep:`425` を見てください。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +#: ../source/guides/distributing-packages-using-setuptools.rst:490 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:" +":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 "" -"MacOS 用の Python インストーラは pip を含んでいます。Linux では、 ``python3-" -"pip`` のような追加のパッケージをインストールしなければならないかもしれませ" -"ん。以下のようにすると pip が最新版であることを確実にすることができます:" +"現在、 :term:`PyPI <` は、Windows向けとmacOS向" +"け、そして複数のLinuxディストリビューションに対応した ``manylinux*`` のABI向" +"けのプラットフォームWheelsをアップロードすることに対応しています。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "プロジェクトをPyPIにアップロードする" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 msgid "" -"Afterwards, you should have the latest version of pip installed in your user " -"site:" +"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 "" -"それから、ユーザサイトには最新版の pip がインストールされているはずです:" +"配布物を作成するコマンドを走らせると、あなたのプロジェクトのルートディレクト" +"リに ``dist/`` という新しいディレクトリが作成されます。ここに配布物のファイル" +"(群)が置かれます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +#: ../source/guides/distributing-packages-using-setuptools.rst:504 msgid "" -"The Python installers for Windows include pip. You can make sure that pip is " -"up-to-date by running:" +"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 " +"or the configuration in your :file:`setup.py` file, you will need to rebuild " +"these files again before you can distribute the changes to PyPI." msgstr "" -"Windows 用の Python インストーラは pip を含んでいます。以下のようにすると " -"pip が最新版であることを確実にすることができます:" - -#: ../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:195 -msgid "Install packages using pip" -msgstr "pip を使ってパッケージをインストールする" +"これらのファイルは、配布物作成のコマンドを走らせたときにだけ作成されます。と" +"いうことは、プロジェクトのソースコードや :file:`setup.py` の中の設定を変更し" +"たときにはいつでも、PyPIへ送る前に配布物のファイルを再作成する必要があるとい" +"うことです。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:509 msgid "" -"When your virtual environment is activated, you can install packages. Use " -"the ``pip install`` command to install packages." +"Before releasing on main PyPI repo, you might prefer training with the `PyPI " +"test site `_ which is cleaned on a semi regular " +"basis. See :ref:`using-test-pypi` on how to setup your configuration in " +"order to use it." msgstr "" -"仮想環境が活性化状態にある時には、パッケージ群をインストールすることができま" -"す。パッケージをインストールするには ``pip install`` コマンドを使ってくださ" +"PyPIの主リポジトリでリリースをする前に、半定期的に消去される `PyPI 試験サイ" +"ト `_ で練習する方が良いかもしれません。どのように設" +"定すれば試験サイトを使えるかについては、 :ref:`using-test-pypi` を見てくださ" "い。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 -msgid "Install a package" -msgstr "パッケージをインストールする" - -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +#: ../source/guides/distributing-packages-using-setuptools.rst:514 msgid "" -"For example,let's install the `Requests`_ library from the :term:`Python " -"Package Index (PyPI)`:" +"In other resources you may encounter references to using ``python setup.py " +"register`` and ``python setup.py upload``. These methods of registering and " +"uploading a package are **strongly discouraged** as it may use a plaintext " +"HTTP or unverified HTTPS connection on some Python versions, allowing your " +"username and password to be intercepted during transmission." msgstr "" -"例として、 :term:`Python Package Index (PyPI)` から `Requests`_ ライブラリを" -"インストールしてみましょう:" +"他のリソースでは、 ``python setup.py register`` と ``python setup.py " +"upload`` に遭遇するかもしれません。これらのメソッドはパッケージを登録ないし" +"アップロードするものですが、 いくつかのバージョンのPythonで使うと平文のHTTPか" +"検証しないHTTPSを用いるのであなたのユーザ名とパスワードが 通信経路上で横取り" +"される恐れがあって **強く非推奨** の状態になっています。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +#: ../source/guides/distributing-packages-using-setuptools.rst:520 msgid "" -"pip should download requests and all of its dependencies and install them:" +"The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " +"ensure safety of all users, certain kinds of URLs and directives are " +"forbidden or stripped out (e.g., the ``.. raw::`` directive). **Before** " +"trying to upload your distribution, you should check to see if your brief / " +"long descriptions provided in :file:`setup.py` are valid. You can do this " +"by running :std:doc:`twine check ` on your package files:" msgstr "" -"pip が requests とその依存先パッケージをすべてダウンロードしてインストールす" -"るはずです:" +"PyPIで使っている reStructuredText パーサは Sphinx **ではありません！** その" +"上、全ユーザの安全を確保するためにある種の URL やディレクティブ(例えば ``.. " +"raw::`` ディレクティブ)は禁止されていたり削除されたりしています。あなたの配布" +"物をアップロードしてみる **前に** :file:`setup.py` の中の brief/long " +"description が文法的に妥当かどうかを確かめるべきです。あなたのパッケージの" +"ファイル群に対して :std:doc:`twine check ` を走らせれば、それを確かめ" +"ることができます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 -msgid "Install a specific package version" -msgstr "特定のバージョンのパッケージをインストールする" +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "アカウントを作成する" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +#: ../source/guides/distributing-packages-using-setuptools.rst:535 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``:" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." msgstr "" -":term:`バージョン指定子 ` を使えば、 pip でパッケージのバー" -"ジョンを指定してインストールすることができます。例えば、 ``requests`` の特定" -"のバージョンをインストールするなら:" - -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 -msgid "To install the latest ``2.x`` release of requests:" -msgstr "requests の最新の ``2.x`` リリースをインストールするには:" +"まず、 :term:`PyPI ` のユーザアカウントが必要で" +"す。 `PyPIウェブサイトにあるフォームを使えば `_ アカウントを作成することができます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 -msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." msgstr "" -"``--pre`` フラグを使ってパッケージのリリース前のバージョンをインストールする" -"には:" - -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 -msgid "Install extras" -msgstr "(パッケージの) extra 部分をインストールする" +"次に PyPI の `API トークン`_ を作成して、プロジェクトを安全にアップロードでき" +"るようにしましょう。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +#: ../source/guides/distributing-packages-using-setuptools.rst:542 msgid "" -"Some packages have optional `extras`_. You can tell pip to install these by " -"specifying the extra in brackets:" +"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 "" -"必須ではない `extra`_ 部分を持つものがパッケージの中にはあります。extra の名" -"前を角括弧([, ])の中に書くことで pip にインストールするように指示することがで" -"きます。" - -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 -msgid "Install a package from source" -msgstr "ソースコードからパッケージをインストールする" +"https://pypi.org/manage/account/#api-tokens and create へ行って、新しい `API " +"トークン`_ を作成してください; これから新しいプロジェクトを作成するわけですか" +"ら、スコープを特定のプロジェクトに限定しないようにしてください。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +#: ../source/guides/distributing-packages-using-setuptools.rst:546 msgid "" -"pip can install a package directly from its source code. For example, to " -"install the source code in the ``google-auth`` directory:" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" msgstr "" -"pip は、ソースコードから直接にパッケージをインストールすることができます。例" -"えば、 ``google-auth`` ディレクトリの中にあるソースコードをインストールするに" -"は:" +"**トークンをコピーして保存するまではページを閉じないでください -- トークンは" +"二度と表示されることがありません。**" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +#: ../source/guides/distributing-packages-using-setuptools.rst:549 msgid "" -"Additionally, pip can install packages from source in :doc:`development mode " -"`, meaning that changes to the source " -"directory will immediately affect the installed package without needing to " -"re-install:" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" msgstr "" -"さらに、 pip は :doc:`開発モード ` で" -"ソースコードからパッケージをインストールすることができます。つまり、ソース" -"コードを修正すると、再インストールしなくても、すぐにインストール済みのパッ" -"ケージに反映されます。" - -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 -msgid "Install from version control systems" -msgstr "バージョン管理システムからインストールする" +":file:`$HOME/.pypirc` ファイルを作っておくことで、アップロードするたびにトー" +"クンをコピー・ペーストする手間を省くことができます。" -#: ../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:" +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -"pip は、バージョン管理システムから直接に、パッケージをインストールすることが" -"できます。例えば、git リポジトリから直接にインストールするには:" +"**このファイルにはトークンが平文で保存されていることに注意してください。**" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +#: ../source/guides/distributing-packages-using-setuptools.rst:560 +#: ../source/guides/migrating-to-pypi-org.rst:74 +#: ../source/guides/migrating-to-pypi-org.rst:113 +#: ../source/guides/using-testpypi.rst:84 msgid "" -"For more information on supported version control systems and syntax, see " -"pip's documentation on :ref:`VCS Support `." +"For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -"サポートされているバージョン管理システムや文法について、詳しくは :ref:`VCS サ" -"ポート ` の pip の説明文書を見てください。" +":file:`.pypirc` についてさらに詳しく知りたい場合は :ref:`specification " +"` を見てください。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 -msgid "Install from local archives" -msgstr "ローカルアーカイブからインストールする" +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "配布物をアップロードする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +#: ../source/guides/distributing-packages-using-setuptools.rst:568 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:" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." msgstr "" -"もし :term:`配布パッケージ ` のアーカイブ ( zip や " -"wheel や tar ファイル) をローカルに持っているなら、 pip でそこから直接にイン" -"ストールすることができます:" +"アカウントが入手できれば、 :ref:`twine` を使ってあなたの配布物を :term:`PyPI " +"` へアップロードすることができます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 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:" +"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 "" -"複数のパッケージのアーカイブを置いたディレクトリを pip に探索させるようにし" -"て、:term:`Python パッケージインデックス ` を全" -"く利用しないということも可能です:" +"リリースをアップロードする手続きは、そのプロジェクトがPyPIに既に存在していて" +"も存在していなくても同じです - もしまだ存在していなければ、最初にリリースが" +"アップロードされたときに自動的に作成されます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +#: ../source/guides/distributing-packages-using-setuptools.rst:575 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." +"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/installing-using-pip-and-virtual-environments.rst:400 -msgid "Install from other package indexes" -msgstr "他のインデックスサイトからインストールする" +"２回目やそれ以降のリリースで PyPI が要求するのは、新しいリリースのバージョン" +"番号が先行するすべてのリリースとは異なるものであることだけです。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 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:" +"You can see if your package has successfully uploaded by navigating to the " +"URL ``https://pypi.org/project/`` where ``sampleproject`` is " +"the name of your project that you uploaded. It may take a minute or two for " +"your project to appear on the site." msgstr "" -":term:`Python パッケージインデックス ` 以外のと" -"ころからパッケージをダウンロードしたいのであれば、 ``--index-url`` オプション" -"でできます:" +"``sampleproject`` のところをアップロードしているプロジェクトの名前に置き換え" +"るとして、 ``https://pypi.org/project/`` に誘導されれば、あな" +"たのパッケージのアップロードは成功です。あなたのプロジェクトがサイト上に表示" +"されるまでには1,2分の時間がかかるかもしれません。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 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:" +"Depending on your platform, this may require root or Administrator access. :" +"ref:`pip` is currently considering changing this by `making user installs " +"the default behavior `_." msgstr "" -":term:`Python パッケージインデックス ` と別のイ" -"ンデックスを同時に使いたいのであれば、 ``--extra-index-url`` オプションででき" -"ます:" +"あなたのプラットフォームに依りますが、これにはrootまたはAdministratorの権限で" +"アクセスしなければならないかもしれません。 :ref:`pip` は現在、 `一般ユーザで" +"のインストールを規定動作にする案 `_ にあるように、この部分の変更を検討しています。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 -#: ../source/tutorials/installing-packages.rst:393 -msgid "Upgrading packages" -msgstr "パッケージを更新する" +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "古いバージョンのPython へのサポートをやめる" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +#: ../source/guides/dropping-older-python-versions.rst:7 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:" +"Dropping support for older Python versions is supported by the standard :ref:" +"`core-metadata` 1.2 specification via a \"Requires-Python\" attribute." msgstr "" -"pip に ``--upgrade`` オプションを与えるとパッケージの入れ替え更新ができます。" -"例えば、 ``requests`` とその依存先パッケージの最新版をインストールしたいのな" -"ら:" +"古いバージョンのPythonへのサポート取りやめは、標準的な :ref:`core-metadata` " +"1.2 仕様の \"Requires-Python\" アトリビュートでサポートされています。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 -msgid "Using a requirements file" -msgstr "requirements ファイルを使う" +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification " +"by matching the current Python runtime and comparing it with the required " +"version in the package metadata. If they do not match, it will attempt to " +"install the last package distribution that supported that Python runtime." +msgstr "" +"Pip 9.0+ のような Metadata 1.2+ のクライアントは、動作中の Python ランタイム" +"のバージョンとパッケージのメタデータで要求されているバージョンを比較突合する" +"ことで、この仕様を遵守しようとします。もし両者が一致しなければ、その Python " +"ランタイムでサポートされているパッケージ配布物の中で最新のものをインストール" +"しようと試みます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +#: ../source/guides/dropping-older-python-versions.rst:12 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:" +"This mechanism can be used to drop support for older Python versions, by " +"amending the \"Requires-Python\" attribute in the package metadata." msgstr "" -"パッケージをひとつひとつインストールする代わりに、pip では :ref:" -"`Requirements ファイル ` にすべての依存先パッケージを" -"列挙しておくことができます。例えば、 :file:`requirements.txt` を下記を含むよ" -"うに作成しておいて:" +"パッケージのメタデータにある \"Requires-Python\" 属性を修正することで、古い" +"バージョンの Python へのサポートを削除するのにこのメカニズムを利用することが" +"できます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +#: ../source/guides/dropping-older-python-versions.rst:14 msgid "" -"And tell pip to install all of the packages in this file using the ``-r`` " -"flag:" +"This guide is specifically for users of :ref:`setuptools`, other packaging " +"tools such as ``flit`` may offer similar functionality but users will need " +"to consult relevant documentation." msgstr "" -"このファイルに書いてあるパッケージを全てインストールするようにと、 ``-r`` オ" -"プションを与えることで pip に指示します:" +"このガイドは特に :ref:`setuptools` のユーザに向けて書かれていますので、同様の" +"機能を提供する ``flit`` のような他のパッケージングツールのユーザは適切な文書" +"を参照する必要があるでしょう。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 -msgid "Freezing dependencies" -msgstr "依存関係を凍結する" +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "Requirements" +msgstr "要求事項" -#: ../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:" +#: ../source/guides/dropping-older-python-versions.rst:19 +msgid "This workflow requires that:" +msgstr "このワークフローは、以下を要求します:" + +#: ../source/guides/dropping-older-python-versions.rst:21 +msgid "The publisher is using the latest version of :ref:`setuptools`," msgstr "" -"Pip では、 ``freeze`` コマンドを使うことで、インストール済みの全パッケージの" -"バージョン付きのリストを取り出すことができます:" +"(パッケージを)公開しようとするものが最新版の :ref:`setuptools` を使っていて、" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 -msgid "Which will output a list of package specifiers such as:" -msgstr "それは、次に挙げるようなパッケージ指定子のリストを出力します:" +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "The latest version of :ref:`twine` is used to upload the package," +msgstr "最新版の :ref:`twine` を使ってパッケージのアップロードを行い、" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 +#: ../source/guides/dropping-older-python-versions.rst:23 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." +"The user installing the package has at least Pip 9.0, or a client that " +"supports the Metadata 1.2 specification." msgstr "" -"``pip freeze`` コマンドは、環境内にインストール済みのすべてのパッケージの正確" -"なバージョンを再生成することができる :ref:`pip:Requirements Files` を作成する" -"のに便利に使えます。" +"パッケージをインストールしようとするユーザが、少なくとも Pip 9.0 か、または、" +"Metadata 1.2 の仕様を満足するクライアントを使っていること。" -#: ../source/guides/installing-using-virtualenv.rst:2 -msgid "Installing packages using virtualenv" -msgstr "virtualenv を使ってパッケージをインストールする" +#: ../source/guides/dropping-older-python-versions.rst:26 +msgid "Dealing with the universal wheels" +msgstr "universal wheelsの取り扱い" -#: ../source/guides/installing-using-virtualenv.rst:4 +#: ../source/guides/dropping-older-python-versions.rst:28 msgid "" -"This guide discusses how to install packages using :ref:`pip` and :ref:" -"`virtualenv`, a tool to create isolated Python environments." +"Traditionally, projects providing Python code that is semantically " +"compatible with both Python 2 and Python 3, produce :term:`wheels ` " +"that have a ``py2.py3`` tag in their names. When dropping support for Python " +"2, it is important not to forget to change this tag to just ``py3``. It is " +"often configured within :file:`setup.cfg` under the ``[bdist_wheel]`` " +"section by setting ``universal = 1`` if they use setuptools." msgstr "" -"このガイド文書では、:ref:`pip` と隔離された Python 環境を作成するツールである" -"ところの :ref:`virtualenv` を使ってパッケージをインストールする方法について議" -"論します。" +"伝統的には、Python 2 と Python 3 の両方で文法的に互換性のある Python ソース" +"コードを提供するプロジェクトは、 ``py2.py3`` というタグをその名前の中に持つ :" +"term:`wheels ` を生成しています。 Python 2 へのサポートをやめる時に" +"は、このタグをただの ``py3`` に変更するのを忘れないことが重要です。 " +"setuptools を使っているのであれば、 :file:`setup.cfg` の中の " +"``[bdist_wheel]`` セクションで ``universal=1`` として設定されています。" -#: ../source/guides/installing-using-virtualenv.rst:8 +#: ../source/guides/dropping-older-python-versions.rst:36 msgid "" -"This \"how to\" guide on installing packages and using :ref:`virtualenv` is " -"under development. Please refer to the :ref:`virtualenv` documentation for " -"details on installation and usage." +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" msgstr "" -"パッケージをインストールすることと :ref:`virtualenv` を使うことに関するこの " -"\"how to\" ガイドは、作成途中です。:ref:`virtualenv` の説明文書にインストール" -"方法や使い方について詳しく出ていますので、そちらもご覧ください。" +"このメソッドを使うのであれば、このオプションないしセクションを削除するか、ま" +"たは、明示的に ``universal`` を ``0`` に設定してください。" -#: ../source/guides/installing-using-virtualenv.rst:13 +#: ../source/guides/dropping-older-python-versions.rst:48 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." +"Since it is possible to override the :file:`setup.cfg` settings via CLI " +"flags, make sure that your scripts don't have ``--universal`` in your " +"package creation scripts." msgstr "" -"この文書では **パッケージ** という用語を :term:`配布パッケージ ` の意味で使いますが、これは Python ソースコードでモジュールをイン" -"ポートするという意味で使われる :term:`パッケージインポート ` " -"とは異なります。" +"CLIでオプションを指定することで :file:`setup.cfg` ファイルでの設定を上書きす" +"ることができるので、あなたのパッケージ生成スクリプトが ``--universal`` オプ" +"ションを指定していないことを確実にしてください。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:2 -msgid "Making a PyPI-friendly README" -msgstr "PyPI によく合う README を作る" +#: ../source/guides/dropping-older-python-versions.rst:53 +msgid "Defining the Python version required" +msgstr "要求する Python のバージョンを定義する" -#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +#: ../source/guides/dropping-older-python-versions.rst:56 +msgid "1. Download the newest version of Setuptools" +msgstr "1. Setuptools の最新版をダウンロードする" + +#: ../source/guides/dropping-older-python-versions.rst:58 msgid "" -"README files can help your users understand your project and can be used to " -"set your project's description on PyPI. This guide helps you create a README " -"in a PyPI-friendly format and include your README in your package so it " -"appears on PyPI." +"Ensure that before you generate source distributions or binary " +"distributions, you update Setuptools and install twine." msgstr "" -"README ファイルは、あなたのパッケージのユーザがプロジェクトを理解するのを助" -"け、プロジェクトの説明をするのに使われています。このガイドでは、PyPI によく合" -"う形で README を作成するのを助け、あなたのパッケージの README が PyPI で表示" -"されるようにします。" +"ソースコード配布物を生成するにせよ、バイナリ配布物を生成するにせよ、 " +"Setuptools を更新し twine をインストールするようにしてください。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:9 -msgid "Creating a README file" -msgstr "README ファイルを作成する" +#: ../source/guides/dropping-older-python-versions.rst:60 +msgid "Steps:" +msgstr "手順:" -#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +#: ../source/guides/dropping-older-python-versions.rst:74 +msgid "``setuptools`` version should be above 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" +msgstr "2. サポートする Python 配布物のバージョンの範囲を指定する" + +#: ../source/guides/dropping-older-python-versions.rst:79 msgid "" -"README files for Python projects are often named ``README``, ``README.txt``, " -"``README.rst``, or ``README.md``." +"You can specify version ranges and exclusion rules, such as at least Python " +"3. Or, Python 2.7, 3.4 and beyond." msgstr "" -"Python プロジェクトにおける READMEファイルは、しばしば ``README`` ・ " -"``README.txt`` ・ ``README.rst`` ・ ``README.md`` などと命名されます。" +"「少なくとも Python 3」や「Python 2.7 か Python 3.5 とそれ以上」などというよ" +"うに、バージョンの範囲や除外のルールを指定することができます。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +#: ../source/guides/dropping-older-python-versions.rst:81 +msgid "Examples:" +msgstr "例:" + +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" -"For your README to display properly on PyPI, choose a markup language " -"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +"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 "" -"あなたの README を PyPI で正しく表示するためには、PyPI がサポートするマーク" -"アップ言語を選択する必要があります。 `PyPI の README レンダラ `_ としてサポートされているのは:" +"このような値の設定は、 :file:`setup.py` スクリプトの中の ``setup`` の呼び出し" +"の中で行えます。 ``python_requires`` 引数に設定した内容に基づいて ``Requires-" +"Python`` メタデータの値が挿入されます。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:16 -msgid "plain text" -msgstr "プレーンテキスト" +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "3. Validating the Metadata before publishing" +msgstr "3. 公開の前にメタデータを検証する" -#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" -"`reStructuredText `_ (without " -"Sphinx extensions)" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." msgstr "" -"`reStructuredText `_ (Sphinx 拡張な" -"し)" +"Python のソースコードパッケージ (あなたがダウンロードしたzipファイルやtar.gz" +"ファイル) の中には、PKG-INFO という名前のテキストファイルがあります。" + +#: ../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 "" +"このファイルは :ref:`distutils` や :ref:`setuptools` でソースコードパッケージ" +"を作成する時に一緒に作成されます。その内容は、一連のキーと値の組み合わせで、" +"キーは Pypa 標準メタデータフォーマットの一部です。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +#: ../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:116 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "パッケージを公開する前に、以下のことが適切かどうかを検証してください。" + +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" -"Markdown (`GitHub Flavored Markdown `_ by " -"default, or `CommonMark `_)" +"If you have upgraded correctly, the Metadata-Version value should be 1.2 or " +"higher." msgstr "" -"マークダウン (デフォルトでは `GitHub Flavored Markdown `_ 、あるいは `CommonMark `_)" +"アップグレードが正しく終われば、Metadata-Version の値が 1.2 かそれ以上になっ" +"ているはずです。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" -"It's customary to save your README file in the root of your project, in the " -"same directory as your :file:`setup.py` file." +"The Requires-Python field is set and matches your specification in setup.py." msgstr "" -"README ファイルについては、 :file:`setup.py` ファイルと同様にプロジェクトの" -"ルートディレクトリに置くのが慣習になっています。" +"Requires-Python フィールドが設定されていて、setup.py でのあなたの指定に一致し" +"ているはずです。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:25 -msgid "Including your README in your package's metadata" -msgstr "README にパッケージのメタデータを含ませる" +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "4. Using Twine to publish" +msgstr "4. Twineを使って公開する" -#: ../source/guides/making-a-pypi-friendly-readme.rst:27 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" -"To include your README's contents as your package description, set your " -"project's ``Description`` and ``Description-Content-Type`` metadata, " -"typically in your project's :file:`setup.py` file." +"Twine has a number of advantages, apart from being faster it is now the " +"supported method for publishing packages." msgstr "" -"README の内容をパッケージの説明として引用させるには、典型的にはプロジェクト" -"の :file:`setup.py` ファイルに、プロジェクトの ``Description`` と " -"``Description-Content-Type`` のふたつのメタデータを設定しておきましょう。" +"動作が速いことを別にしてもTwineには数多くの利点があり、今ではパッケージを公開" +"するためのメソッドとしてサポートされています。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:33 -msgid ":ref:`description-optional`" -msgstr ":ref:`description-optional`" +#: ../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/making-a-pypi-friendly-readme.rst:34 -msgid ":ref:`description-content-type-optional`" -msgstr ":ref:`description-content-type-optional`" +#: ../source/guides/dropping-older-python-versions.rst:129 +msgid "Dropping a Python release" +msgstr "Pythonリリースをサポートから外す" -#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" -"For example, to set these values in a package's :file:`setup.py` file, use " -"``setup()``'s ``long_description`` and ``long_description_content_type``." +"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 "" -"例えば、これらの値をパッケージの :file:`setup.py` ファイルに設定するために" -"は、 ``setup()`` の ``long_description`` と " -"``long_description_content_type`` を使ってください。" +"Requires-Python メタデータ付きでパッケージを公開しさえすれば、次回以降の更新" +"の際にPython ランタイムをサポートから外すことができるようになります。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:39 -msgid "" -"Set the value of ``long_description`` to the contents (not the path) of the " -"README file itself. Set the ``long_description_content_type`` to an accepted " -"``Content-Type``-style value for your README file's markup, such as ``text/" -"plain``, ``text/x-rst`` (for reStructuredText), or ``text/markdown``." +#: ../source/guides/dropping-older-python-versions.rst:133 +msgid "It must be done in this order for the automated fallback to work." msgstr "" -"``long_desctription`` には README ファイルの内容それ自体 (パスではなく) を設" -"定してください。 ``long_description_content_type`` には、README ファイルの" -"マークアップの型を受け入れ可能な ``Content-Type`` 風の書き方、すなわち " -"``text/plain`` ・ ``text/x-rst`` (reStructuredText の場合) ・ ``text/" -"markdown`` から選んで設定してください。" +"自動フォールバックが正しく動作するためには、この順番で行わなければなりませ" +"ん。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" -"If you're using GitHub-flavored Markdown to write a project's description, " -"ensure you upgrade the following tools:" +"For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " +"of your package." msgstr "" -"プロジェクトの説明を GitHub 方言のマークダウンで書くのであれば、以下のツール" -"を更新しておくことを忘れないでください:" - -#: ../source/guides/making-a-pypi-friendly-readme.rst:60 -msgid "The minimum required versions of the respective tools are:" -msgstr "各ツールは少なくとも次のバージョンでなければなりません:" +"例えば、 Requires-Python: \">=2.7\" の状態であなたのパッケージのバージョン " +"1.0.0 を公開したとしましよう。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:62 -msgid "``setuptools >= 38.6.0``" +#: ../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 " +"2.7 will have version 1.0.0 of the package installed, and any >=3.5 users " +"will receive version 2.0.0." msgstr "" +"その後、バージョン文字列を \">=3.5\" に修正した新しいバージョン 2.0.0 のパッ" +"ケージを公開すれば、Pip 9.0+ を 2.7 で使っているユーザはバージョン 1.0.0. の" +"パッケージをインストールし、>=3.5 のユーザはバージョン 2.0.0 を受け取ることに" +"なるでしょう。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:63 -msgid "``wheel >= 0.31.0``" -msgstr "" +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "あなた自身の単純なリポジトリをホストする" -#: ../source/guides/making-a-pypi-friendly-readme.rst:64 -msgid "``twine >= 1.11.0``" +#: ../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 simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" +"あなた自身の単純なリポジトリ [1]_ をホストしたいのであれば、 :doc:`devpi " +"` のようなソフトウェアパッケージを使うこともできますし、単に " +"web サーバ上に適切なディレクトリを作成して静的ファイルを提供し自動でインデッ" +"クスを生成させることも可能です。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +#: ../source/guides/hosting-your-own-index.rst:13 msgid "" -"It's recommended that you use ``twine`` to upload the project's distribution " -"packages:" +"In either case, since you'll be hosting a repository that is likely not in " +"your user's default repositories, you should instruct them in your project's " +"description to configure their installer appropriately. For example with pip:" msgstr "" -"プロジェクトの配布物パッケージをアップロードする時は ``twine`` を使うことを推" -"奨します。" +"どちらの場合でも、ユーザとしての既定のリポジトリではない場所をあなたのリポジ" +"トリにしようとしているのでしょうから、あなたのプロジェクトの説明にインストー" +"ラを適切に設定するように指図しておくべきでしょう。例えば pip なら:" -#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +#: ../source/guides/hosting-your-own-index.rst:29 msgid "" -"For example, see this :file:`setup.py` file, which reads the contents of :" -"file:`README.md` as ``long_description`` and identifies the markup as GitHub-" -"flavored Markdown:" +"In addition, it is **highly** recommended that you serve your repository " +"with valid HTTPS. At this time, the security of your user's installations " +"depends on all repositories using a valid HTTPS setup." msgstr "" -"例えば、この :file:`setup.py` ファイルでは、 :file:`README.md` の内容を読み" -"取って ``long_description`` としていて、マークアップ方式は GitHub 方言のマー" -"クダウンを指定しています:" +"加えて、あなたのリポジトリを公開する場合はHTTPSで公開することが強く推奨されま" +"す。この時、ユーザがあなたのパッケージをインストールする際のセキュリティは、" +"すべてのリポジトリが適切なHTTPS設定であるか否かに依存します。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:94 -msgid "Validating reStructuredText markup" -msgstr "reStructuredText マークアップを検証する" +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "\"手動\"リポジトリ" -#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +#: ../source/guides/hosting-your-own-index.rst:37 msgid "" -"If your README is written in reStructuredText, any invalid markup will " -"prevent it from rendering, causing PyPI to instead just show the README's " -"raw source." +"The directory layout is fairly simple, within a root directory you need to " +"create a directory for each project. This directory should be the :ref:" +"`normalized name ` of the project. Within each of these " +"directories simply place each of the downloadable files. If you have the " +"projects \"Foo\" (with the versions 1.0 and 2.0) and \"bar\" (with the " +"version 0.1) You should end up with a structure that looks like::" msgstr "" -"README を reStructuredText で書いている場合、無効なマークアップがひとつでもあ" -"ると描画できないので、PyPI 上では README の生のソースコードを表示するだけに" -"なってしまいます。" +"ディレクトリ構造は極めて単純で、ルートディレクトリ内に各プロジェクトを納めた" +"ディレクトリを作成する必要があります。このディレクトリは、プロジェクトの :" +"ref:`標準化された名前 ` になっているべきです。各プロジェ" +"クトのディレクトリには、それぞれダウンロード可能なファイルを置くだけで" +"す。\"Foo\" というプロジェクト (のバージョン 1.0 と 2.0) と \"bar\" というプ" +"ロジェクト (のバージョン 0.1) があるなら、ディレクトリ構造はこんなふうになる" +"でしょう::" -#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +#: ../source/guides/hosting-your-own-index.rst:50 msgid "" -"Note that Sphinx extensions used in docstrings, such as :doc:`directives " -"` and :doc:`roles ` (e.g., \"``:py:func:`getattr```\" or \"``:ref:`my-" -"reference-label```\"), are not allowed here and will result in error " -"messages like \"``Error: Unknown interpreted text role \"py:func\".``\"." +"Once you have this layout, simply configure your webserver to serve the root " +"directory with autoindex enabled. For an example using the built in Web " +"server in `Twisted`_, you would simply run ``twistd -n web --path .`` and " +"then instruct users to add the URL to their installer's configuration." msgstr "" -":doc:`ディレクティブ ` と :doc:`" -"ロール ` (例えば \"``:py:func:" -"`getattr```\" や \"``:ref:`my-reference-label```\") のように docstrings 内で" -"使われる Sphinx 拡張はこの場所では使用を許されず、 ``Error: テキストロール " -"\"py:func\" が見つかりません。`` " -"といったエラーメッセージを出すことになります。" +"この配置ができあがったら、あとはルートディレクトリを自動インデックス付きで" +"ウェブサーバから提供するように設定するだけです。 `Twisted`_ の組み込みウェブ" +"サーバを使う例では、単に ``twisted -n web --path.`` を走らせておいて、ユーザ" +"に対してこのURLをインストーラの設定に加えるように指示するだけです。" -#: ../source/guides/making-a-pypi-friendly-readme.rst:104 -msgid "" -"You can check your README for markup errors before uploading as follows:" -msgstr "" -"README ファイルのマークアップに関するエラーをアップロードする前に確認するに" -"は、次のようにします:" +#: ../source/guides/hosting-your-own-index.rst:57 +#: ../source/guides/index-mirrors-and-caches.rst:47 +msgid "Existing projects" +msgstr "既存のプロジェクト" + +#: ../source/guides/hosting-your-own-index.rst:63 +msgid "Package upload" +msgstr "パッケージアップロード" + +#: ../source/guides/hosting-your-own-index.rst:64 +msgid "PyPI fall-through [2]_" +msgstr "PyPI フォールスルー [2]_" + +#: ../source/guides/hosting-your-own-index.rst:65 +#: ../source/guides/index-mirrors-and-caches.rst:56 +#: ../source/guides/supporting-windows-using-appveyor.rst:146 +msgid "Additional notes" +msgstr "補遺" + +#: ../source/guides/hosting-your-own-index.rst:67 +#: ../source/guides/index-mirrors-and-caches.rst:58 +msgid ":ref:`devpi`" +msgstr ":ref:`devpi`" + +#: ../source/guides/hosting-your-own-index.rst:68 +#: ../source/guides/hosting-your-own-index.rst:69 +#: ../source/guides/hosting-your-own-index.rst:75 +#: ../source/guides/hosting-your-own-index.rst:79 +#: ../source/guides/hosting-your-own-index.rst:99 +#: ../source/guides/hosting-your-own-index.rst:120 +#: ../source/guides/index-mirrors-and-caches.rst:59 +#: ../source/guides/index-mirrors-and-caches.rst:60 +#: ../source/guides/index-mirrors-and-caches.rst:66 +#: ../source/guides/index-mirrors-and-caches.rst:67 +#: ../source/guides/index-mirrors-and-caches.rst:74 +#: ../source/guides/index-mirrors-and-caches.rst:78 +#: ../source/guides/index-mirrors-and-caches.rst:80 +#: ../source/guides/index-mirrors-and-caches.rst:85 +#: ../source/guides/index-mirrors-and-caches.rst:86 +#: ../source/guides/index-mirrors-and-caches.rst:90 +#: ../source/guides/index-mirrors-and-caches.rst:92 +#: ../source/guides/index-mirrors-and-caches.rst:96 +#: ../source/guides/index-mirrors-and-caches.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:102 +#: ../source/guides/index-mirrors-and-caches.rst:104 +#: ../source/guides/index-mirrors-and-caches.rst:108 +#: ../source/guides/index-mirrors-and-caches.rst:110 +msgid "✔" +msgstr "✔" -#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +#: ../source/guides/hosting-your-own-index.rst:70 msgid "" -"Install the latest version of `twine `_; " -"version 1.12.0 or higher is required:" -msgstr "" -"最新版の `twine `_ をインストールします; バー" -"ジョン 1.12.0 またはそれ以上のものが必須です:" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "同期、複製、フェールオーバ、ミラーリングが可能な複数のインデックス" -#: ../source/guides/making-a-pypi-friendly-readme.rst:121 -msgid "" -"Build the sdist and wheel for your project as described under :ref:" -"`Packaging Your Project`." -msgstr "" -":ref:`あなたのプロジェクトをパッケージする ` に記述さ" -"れているように、プロジェクトの sdist と wheel をビルドします。" +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr ":ref:`simpleindex`" -#: ../source/guides/making-a-pypi-friendly-readme.rst:124 -msgid "Run ``twine check`` on the sdist and wheel:" -msgstr "sdist と wheel に対して ``twine check`` を実行します:" +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr ":ref:`pypiserver`" -#: ../source/guides/making-a-pypi-friendly-readme.rst:130 -msgid "" -"This command will report any problems rendering your README. If your markup " -"renders fine, the command will output ``Checking distribution FILENAME: " -"Passed``." -msgstr "" -"このコマンドは README のレンダリングに関する問題があれば報告するでしょう。" -"マークアップのレンダリングに問題がなければ、 ``配布物を検査しています " -"FILENAME: 合格 `` と出力するでしょ" -"う。" +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr ":ref:`pypiprivate`" -#: ../source/guides/migrating-to-pypi-org.rst:6 -msgid "Migrating to PyPI.org" -msgstr "PyPI.org へ移設する" +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr ":ref:`pypicloud`" -#: ../source/guides/migrating-to-pypi-org.rst:8 -#: ../source/guides/multi-version-installs.rst:8 -#: ../source/guides/supporting-multiple-python-versions.rst:9 -#: ../source/guides/supporting-windows-using-appveyor.rst:7 -msgid "Obsolete" -msgstr "古い情報" +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "メンテナンスされていない; またプロクシでキャッシュ; 認証、認可" -#: ../source/guides/migrating-to-pypi-org.rst:10 -msgid "" -":term:`pypi.org` is the new, rewritten version of PyPI that has replaced the " -"legacy PyPI code base. It is the default version of PyPI that people are " -"expected to use. These are the tools and processes that people will need to " -"interact with ``PyPI.org``." -msgstr "" -":term:`pypi.org` は、新しくて書き直されたバージョンの PyPI で、以前の PyPI " -"コードベースを置き換えるものです。みなさんが普通はこれを使うものと期待されて" -"いるバージョンの PyPI です。 ``PyPI.org`` とやり取りするためのツールや手順が" -"あります。" +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr ":ref:`pywharf`" -#: ../source/guides/migrating-to-pypi-org.rst:16 -msgid "Publishing releases" -msgstr "リリースを公開する" +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "メンテナンスされていない; GitHub内のファイルを提供する" -#: ../source/guides/migrating-to-pypi-org.rst:18 -msgid "``pypi.org`` is the default upload platform as of September 2016." -msgstr "" -"2016年9月以降、 ``pypi.org`` がデフォルトのアップロードプラットフォームです。" +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr ":ref:`pulppython`" -#: ../source/guides/migrating-to-pypi-org.rst:20 -msgid "" -"Uploads through ``pypi.python.org`` were *switched off* on **July 3, 2017**. " -"As of April 13th, 2018, ``pypi.org`` is the URL for PyPI." -msgstr "" -"``pypi.python.org`` を通じたアップロードは **2017年7月3日** に使用不可能にな" -"りました。2018年4月13日以降は、``pypi.org`` が PyPI のURLです。" +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "また、ミラーリング、プロクシ利用; Pulp 用のプラグイン" -#: ../source/guides/migrating-to-pypi-org.rst:23 -msgid "" -"The recommended way to migrate to PyPI.org for uploading is to ensure that " -"you are using a new enough version of your upload tool." -msgstr "" -"PyPI.org へ移行するためのアップロードでは、アップロードに使うツールが十分に新" -"しいバージョンのものであることを確実にしておくことが推奨されます。" +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr ":ref:`pip2pi`" -#: ../source/guides/migrating-to-pypi-org.rst:26 -msgid "" -"The default upload settings switched to ``pypi.org`` in the following " -"versions:" -msgstr "" -"``pypi.org`` に転換するためのデフォルトのアップロード設定は次のようなバージョ" -"ンです:" +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "また、ミラーリング; 手動の同期" -#: ../source/guides/migrating-to-pypi-org.rst:28 -msgid "``twine`` 1.8.0" -msgstr "" +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr ":ref:`dumb-pypi`" -#: ../source/guides/migrating-to-pypi-org.rst:29 -msgid "``setuptools`` 27.0.0" -msgstr "" +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "サーバではなくて、静的ファイルのサイトのジェネレータ" -#: ../source/guides/migrating-to-pypi-org.rst:30 -msgid "Python 2.7.13 (``distutils`` update)" -msgstr "Python 2.7.13 (``distutils`` 更新)" +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr ":ref:`httpserver`" -#: ../source/guides/migrating-to-pypi-org.rst:31 -msgid "Python 3.4.6 (``distutils`` update)" -msgstr "Python 3.4.6 (``distutils`` 更新)" +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "標準ライブラリ" -#: ../source/guides/migrating-to-pypi-org.rst:32 -msgid "Python 3.5.3 (``distutils`` update)" -msgstr "Python 3.5.3 (``distutils`` 更新)" +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "`Apache `_" -#: ../source/guides/migrating-to-pypi-org.rst:33 -msgid "Python 3.6.0 (``distutils`` update)" -msgstr "Python 3.6.0 (``distutils`` 更新)" +#: ../source/guides/hosting-your-own-index.rst:121 +#: ../source/guides/index-mirrors-and-caches.rst:111 +msgid "" +"using `mod_rewrite `_ and `mod_cache_disk `_, you can cache requests to package indexes through an " +"Apache server" +msgstr "" +"`mod_rewrite `_ " +"および `mod_cache_disk `_ を用いて、Apache サーバ経由のパッケージインデックスへ" +"のリクエストをキャッシュすることができます" -#: ../source/guides/migrating-to-pypi-org.rst:35 +#: ../source/guides/hosting-your-own-index.rst:131 msgid "" -"In addition to ensuring you're on a new enough version of the tool for the " -"tool's default to have switched, you must also make sure that you have not " -"configured the tool to override its default upload URL. Typically this is " -"configured in a file located at :file:`$HOME/.pypirc`. If you see a file " -"like:" +"For complete documentation of the simple repository protocol, see :ref:" +"`simple repository API `." msgstr "" -"ツールのデフォルト設定が切り替わっている程に十分に新しいツールを使っているこ" -"とを確認するのに加えて、そのデフォルトのアップロード先 URL を上書きするような" -"設定をしていないことを確実にしてください。これは典型的には file:`$HOME/." -"pypirc` で設定されています。もしこんなファイルを目にするようであれば:" +"単純なリポジトリプロトコルの完全な説明文書としては、 :ref:`simple repository " +"API ` を見てください。" -#: ../source/guides/migrating-to-pypi-org.rst:52 +#: ../source/guides/hosting-your-own-index.rst:134 msgid "" -"Then simply delete the line starting with ``repository`` and you will use " -"your upload tool's default URL." +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." msgstr "" -"その時は、 ``repository`` で始まる行を削除するだけで、アップロードツールのデ" -"フォルト URL を使うようになります。" +"要求されたパッケージが存在しなければ、 PyPI (もしくは他のパッケージインデック" +"ス) へフォールバックするように設定しておくことができます。" -#: ../source/guides/migrating-to-pypi-org.rst:55 +#: ../source/guides/index.rst:4 msgid "" -"If for some reason you're unable to upgrade the version of your tool to a " -"version that defaults to using PyPI.org, then you may edit :file:`$HOME/." -"pypirc` and include the ``repository:`` line, but use the value ``https://" -"upload.pypi.org/legacy/`` instead:" +"**Guides** are focused on accomplishing a specific task and assume that you " +"are already familiar with the basics of Python packaging. If you're looking " +"for an introduction to packaging, see :doc:`/tutorials/index`." msgstr "" -"なんらかの事情でPyPI.orgをデフォルトで使うところまでアップロードツールのバー" -"ジョンを上げられないのであれば、 :file:`$HOME/.pypirc` で ``repository:`` 行" -"が ``https://upload.pypi.org/legacy/`` を指すように編集しても構いません。" +"**ガイド文書** は特定のタスクを達成することに重点を置くもので、読者が Python " +"のパッケージングの基礎について既に馴染みがあるものと仮定しています。パッケー" +"ジングの導入的な説明を探しているのであれば :doc:`/tutorials/index` を見てくだ" +"さい。" -#: ../source/guides/migrating-to-pypi-org.rst:71 +#: ../source/guides/index-mirrors-and-caches.rst:5 +msgid "Package index mirrors and caches" +msgstr "パッケージインデックスのミラーとキャッシュ" + +#: ../source/guides/index-mirrors-and-caches.rst:8 +msgid "2023-11-08" +msgstr "2023年11月8日" + +#: ../source/guides/index-mirrors-and-caches.rst:10 msgid "" -"(``legacy`` in this URL refers to the fact that this is the new server " -"implementation's emulation of the legacy server implementation's upload API.)" +"Mirroring or caching of PyPI (and other :term:`package indexes `) can be used to speed up local package installation, allow offline " +"work, handle corporate firewalls or just plain Internet flakiness." msgstr "" -"(この URL の中の ``legacy`` は、新しいサーバ実装が、以前のサーバ実装のアップ" -"ロード API をエミュレートしているという事実を示しています。)" +"PyPI (あるいは他の :term:`パッケージインデックス `) のミラーや" +"キャッシュがあると、手元でパッケージをインストールするのが速くなったり、オフ" +"ラインでインストールできたり、会社のファイアウォール経由でもできたり、あるい" +"は、単純にインターネットがあてにならなくてもインストールできたりします。" -#: ../source/guides/migrating-to-pypi-org.rst:77 -msgid "Registering package names & metadata" -msgstr "パッケージの名前とメタデータを登録する" +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "この領域のオプションには複数のクラスがあります:" -#: ../source/guides/migrating-to-pypi-org.rst:79 +#: ../source/guides/index-mirrors-and-caches.rst:17 +msgid "local/hosted caching of package indexes." +msgstr "パッケージインデックスのローカルまたはホストされたキャッシュ。" + +#: ../source/guides/index-mirrors-and-caches.rst:19 msgid "" -"Explicit pre-registration of package names with the ``setup.py register`` " -"command prior to the first upload is no longer required, and is not " -"currently supported by the legacy upload API emulation on PyPI.org." +"local/hosted mirroring of a package index. A mirror is a (whole or partial) " +"copy of a package index, which can be used in place of the original index." msgstr "" -"初回のアップロードに先立って ``setup.py register`` コマンドでパッケージの名前" -"を明示的に先行登録する必要がなくなり、PyPI.org における以前のアップロード " -"API のエミュレーションではサポートされなくなりました。" +"パッケージインデックスのローカルまたはホストされたミラーリング。ミラーとは、" +"パッケージインデックスの (全体または一部の) コピーで、オリジナルのインデック" +"スの代わりに使うことができます。" + +#: ../source/guides/index-mirrors-and-caches.rst:23 +msgid "" +"private package index with fall-through to public package indexes (for " +"example, to mitigate dependency confusion attacks), also known as a proxy." +msgstr "" +"(例えば依存関係を混乱させる攻撃を緩和するための) 公開のパッケージインデックス" +"へフォールスルーする機能を持ったプライベートなパッケージインデックスで、プロ" +"クシーとも呼ばれる。" + +#: ../source/guides/index-mirrors-and-caches.rst:29 +msgid "Caching with pip" +msgstr "pipによるキャッシュ" -#: ../source/guides/migrating-to-pypi-org.rst:83 +#: ../source/guides/index-mirrors-and-caches.rst:31 msgid "" -"As a result, attempting explicit registration after switching to using PyPI." -"org for uploads will give the following error message::" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" msgstr "" -"その結果、アップロードに PyPI.org を使うように切り替えた後は明示的な登録の試" -"行は次のエラーメッセージを返すでしょう::" +"pip は、 :term:`パッケージ ` のローカルキャッシュを使っ" +"て素早くインストールするためのいくつもの機能を提供します。" -#: ../source/guides/migrating-to-pypi-org.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:34 msgid "" -"The solution is to skip the registration step, and proceed directly to " -"uploading artifacts." +":ref:`Fast & local installs ` by " +"downloading all the requirements for a project and then pointing pip at " +"those downloaded files instead of going to PyPI." msgstr "" -"解決方法は登録の段階を飛ばしていきなり作品のアップロードへと進むことです。" - -#: ../source/guides/migrating-to-pypi-org.rst:93 -#: ../source/guides/using-testpypi.rst:5 -msgid "Using TestPyPI" -msgstr "TestPyPI を使う" +"あるプロジェクトの依存先パッケージをすべてダウンロードし、 pip を PyPI の代わ" +"りにそれらダウンロード済みファイルに向けることによる :ref:`速くてローカルなイ" +"ンストール ` 。" -#: ../source/guides/migrating-to-pypi-org.rst:95 +#: ../source/guides/index-mirrors-and-caches.rst:37 msgid "" -"Legacy TestPyPI (testpypi.python.org) is no longer available; use `test.pypi." -"org `_ instead. If you use TestPyPI, you must update " -"your :file:`$HOME/.pypirc` to handle TestPyPI's new location, by replacing " -"``https://testpypi.python.org/pypi`` with ``https://test.pypi.org/legacy/``, " -"for example:" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" msgstr "" -"以前からの TestPyPI (testpypi.python.org) はもはや利用できませんので、代わり" -"に `test.pypi.org `_ を使ってください。 TestPyPI を使" -"うのであれば、 :file:`$HOME/.pypirc` で ``https://testpypi.python.org/pypi`` " -"を ``https://test.pypi.org/legacy/`` に置き換えるなどして、 TestPyPI の新しい" -"場所を使うように設定しなければなりません。例えば:" +":ref:`python -m pip wheel ` を用いて依存先パッケージのインス" +"トール用ファイルをあらかじめビルドしておくという上記のバリエーション:" -#: ../source/guides/migrating-to-pypi-org.rst:117 -msgid "Registering new user accounts" -msgstr "新しいユーザアカウントを登録する" +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "キャッシュ" -#: ../source/guides/migrating-to-pypi-org.rst:119 +#: ../source/guides/index-mirrors-and-caches.rst:54 +msgid "Mirror" +msgstr "ミラー" + +#: ../source/guides/index-mirrors-and-caches.rst:55 +msgid "Proxy" +msgstr "プロクシ" + +#: ../source/guides/index-mirrors-and-caches.rst:62 msgid "" -"In order to help mitigate spam attacks against PyPI, new user registration " -"through ``pypi.python.org`` was *switched off* on **February 20, 2018**. New " -"user registrations at ``pypi.org`` are open." +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" msgstr "" -"PyPI に対するスパム攻撃を緩和する補助するために、 ``pypi.python.org`` におけ" -"る新規ユーザ登録は **2018年2月20日** に *終了* しました。 ``pypi.org`` での新" -"規ユーザ登録が始まっています。" +"継承・同期・複製・フェイルオーバ・パッケージアップロードの機能を持つ複数のイ" +"ンデックス群" -#: ../source/guides/migrating-to-pypi-org.rst:125 -msgid "Browsing packages" -msgstr "パッケージを一覧する" +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr ":ref:`bandersnatch`" -#: ../source/guides/migrating-to-pypi-org.rst:127 -msgid "" -"While ``pypi.python.org`` is may still be used in links from other PyPA " -"documentation, etc, the default interface for browsing packages is ``pypi." -"org``. The domain pypi.python.org now redirects to pypi.org, and may be " -"disabled sometime in the future." +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" msgstr "" -"``pypi.python.org`` が他の PyPA 説明文書などからのリンクに使われているとして" -"も、パッケージを一覧するデフォルトのインタフェイスは ``pypi.org`` です。pupi." -"python.org ドメイン名は今は pypi.org へリダイレクトされていて、いつか将来の時" -"点で無効にされるでしょう。" +"カスタムプラグインによってキャッシングや他のパッケージインデックスへのリルー" +"ティングが可能になります" -#: ../source/guides/migrating-to-pypi-org.rst:134 -msgid "Downloading packages" -msgstr "パッケージをダウンロードする" +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "保守されていない; 認証・認可" -#: ../source/guides/migrating-to-pypi-org.rst:136 -msgid "``pypi.org`` is the default host for downloading packages." +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" msgstr "" -"``pypi.org`` が、パッケージをダウンロードする際のデフォルトのホストです。" +"Pulp 用のプラグイン; 複数のプロクシされたインデックス; パッケージアップロード" -#: ../source/guides/migrating-to-pypi-org.rst:139 -msgid "Managing published packages and releases" -msgstr "公開済みパッケージとリリースを管理する" +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr ":ref:`proxpi`" -#: ../source/guides/migrating-to-pypi-org.rst:141 +#: ../source/guides/index-mirrors-and-caches.rst:93 +#: ../source/guides/index-mirrors-and-caches.rst:99 +msgid "multiple proxied indexes" +msgstr "複数のプロクシされたインデックス群" + +#: ../source/guides/index-mirrors-and-caches.rst:95 +msgid ":ref:`nginx_pypi_cache`" +msgstr ":ref:`nginx_pypi_cache`" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr ":ref:`flaskpypiproxy`" + +#: ../source/guides/index-mirrors-and-caches.rst:105 +msgid "unmaintained" +msgstr "保守されていない" + +#: ../source/guides/installing-scientific-packages.rst:5 +msgid "Installing scientific packages" +msgstr "科学分野のパッケージをインストールする" + +#: ../source/guides/installing-scientific-packages.rst:8 msgid "" -"``pypi.org`` provides a fully functional interface for logged in users to " -"manage their published packages and releases." +"Scientific software tends to have more complex dependencies than most, and " +"it will often have multiple build options to take advantage of different " +"kinds of hardware, or to interoperate with different pieces of external " +"software." msgstr "" -"``pypi.org`` では、ログインしたユーザが自分が公開したプロジェクトやリリースに" -"ついて管理するための全機能を提供しています。" - -#: ../source/guides/modernize-setup-py-project.rst:6 -msgid "How to modernize a ``setup.py`` based project?" -msgstr "どうすれば ``setup.py`` ベースのプロジェクトを近代化できるでしょうか？" +"科学分野のソフトウェアは、他のほとんどのものよりも複雑な依存関係を持つことが" +"多く、異なる種類のハードウェアの利点を引き出すためや外部のソフトウェアのさま" +"ざまな部分と協調動作するためのオプションが複数存在することもしばしばです。" -#: ../source/guides/modernize-setup-py-project.rst:10 -msgid "Should ``pyproject.toml`` be added?" -msgstr "``pyproject.toml`` を追加するべきですか？" +#: ../source/guides/installing-scientific-packages.rst:13 +msgid "" +"In particular, `NumPy `__, which provides the basis for " +"most of the software in the `scientific Python stack `_ can be configured to interoperate with different FORTRAN " +"libraries, and can take advantage of different levels of vectorised " +"instructions available in modern CPUs." +msgstr "" +"とりわけ `科学分野のPythonソフトウェア群 `_ の" +"ほとんどのソフトウェアに基盤を提供する`NumPy `__ は、他" +"の FORTRAN ライブラリと協調動作したり現代的なCPUで利用可能なさまざまなレベル" +"のベクター演算命令を活用できるように構成可能です。" -#: ../source/guides/modernize-setup-py-project.rst:12 +#: ../source/guides/installing-scientific-packages.rst:19 msgid "" -"A :term:`pyproject.toml` file is strongly recommended. The presence of a :" -"file:`pyproject.toml` file itself does not bring much. [#]_ What is actually " -"strongly recommended is the ``[build-system]`` table in :file:`pyproject." -"toml`." +"Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built " +"32-bit and 64-bit binaries in the ``wheel`` format are available for all " +"major operating systems (Windows, macOS, and Linux) on PyPI. Note, however, " +"that on Windows, NumPy binaries are linked against the `ATLAS `__ BLAS/LAPACK library, restricted to SSE2 instructions, " +"so they may not provide optimal linear algebra performance." msgstr "" -":term:`pyproject.toml` ファイルは強く推奨されています。:file:`pyproject." -"toml` ファイルが存在すること自体は多くをもたらすものではありません。 [#]_ 実" -"際に強く推奨されているものは、:file:`pyproject.toml` の中の ``[build-" -"system]`` テーブルです。" +"Numpy のバージョン 1.10.4 および SciPy のバージョン 1.0.0 以降は、 主要なオペ" +"レーティングシステム (WindowsとmacOSとLinux)向けに32 ビットと 64 ビットのビル" +"ド済みバイナリが ``wheel`` 形式でPyPIに準備されています。ただ、Windowsでは、" +"SSE2命令セットに限定された `ATLAS `__ BLAS/" +"LAPACK ライブラリに NumPy がリンクされているので、線形代数のパフォーマンスが" +"最適化されていない可能性があります。" -#: ../source/guides/modernize-setup-py-project.rst:16 +#: ../source/guides/installing-scientific-packages.rst:26 msgid "" -"Note that it has influence on the build isolation feature of pip, see below." +"There are a number of alternative options for obtaining scientific Python " +"libraries (or any other Python libraries that require a compilation " +"environment to install from source and don't provide pre-built wheel files " +"on PyPI)." msgstr "" -"以下のように、これが pip のビルド隔離機能に影響を与えるということを銘記してく" -"ださい。" +"科学分野の Python ライブラリ (または、ソースコードからインストールする際にコ" +"ンパイル環境を必要とするが、 PyPI にビルド済みの wheel ファイルが用意されてい" +"ないような、他の全ての Python ライブラリ) を手に入れるには他にも数多くの代替" +"方法があります。" -#: ../source/guides/modernize-setup-py-project.rst:23 +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "ソースコードからビルドする" + +#: ../source/guides/installing-scientific-packages.rst:34 msgid "" -"No, :file:`setup.py` can exist in a modern :ref:`setuptools` based project. " -"The :term:`setup.py` file is a valid configuration file for setuptools that " -"happens to be written in Python. However, the following commands are " -"deprecated and **MUST NOT** be run anymore, and their recommended " -"replacement commands should be used instead:" +"The same complexity which makes it difficult to distribute NumPy (and many " +"of the projects that depend on it) as wheel files also make them difficult " +"to build from source yourself. However, for intrepid folks that are willing " +"to spend the time wrangling compilers and linkers for both C and FORTRAN, " +"building from source is always an option." msgstr "" -"いいえ、 :file:`setup.py` は、近代的な :ref:`setuptools` ベースのプロジェクト" -"にあっても構いません。 :term:`setup.py` ファイルは、たまたま Python で書かれ" -"ている setuptools 向けの正当な設定ファイルなのです。しかしながら、以下のコマ" -"ンド群は非推奨になっていてもはや実行することは **許されず** 、その代わりに以" -"下のようなコマンドを使用するべきです:" +"NumPy (およびそれに依存するプロジェクトの多く) を wheel ファイルとして配布す" +"ることを難しくする同じ複雑さが、自分でソースコードから作成することをも困難に" +"しています。しかしながら、C言語やFORTRAN言語のコンパイラやリンカを説得するの" +"に喜んで時間を費やそうという勇敢な人々にとっては、ソースコードからビルドする" +"ことは常にひとつの選択肢です。" -#: ../source/guides/modernize-setup-py-project.rst:36 -msgid "``python -m build``" -msgstr "``python -m build``" +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +msgstr "Linux 配布パッケージ" -#: ../source/guides/modernize-setup-py-project.rst:42 -#: ../source/guides/modernize-setup-py-project.rst:66 -#: ../source/guides/modernize-setup-py-project.rst:111 -#: ../source/guides/modernize-setup-py-project.rst:129 -#: ../source/guides/modernize-setup-py-project.rst:221 -msgid "For more details:" -msgstr "より詳しくは:" +#: ../source/guides/installing-scientific-packages.rst:44 +msgid "" +"For Linux users, the system package manager will often have pre-compiled " +"versions of various pieces of scientific software, including NumPy and other " +"parts of the scientific Python stack." +msgstr "" +"Linux のユーザなら、システムのパッケージマネージャを使えば NumPy やその他の科" +"学分野のPythonソフトウェア群のコンパイル済みのパッケージが準備されていること" +"も多々あります。" -#: ../source/guides/modernize-setup-py-project.rst:44 -msgid ":ref:`setup-py-deprecated`" -msgstr ":ref:`setup-py-deprecated`" +#: ../source/guides/installing-scientific-packages.rst:48 +msgid "" +"If using versions which may be several months old is acceptable, then this " +"is likely to be a good option (just make sure to allow access to " +"distributions installed into the system Python when using virtual " +"environments)." +msgstr "" +"もし数ヶ月遅れでも構わないのであれば、これは良い選択肢でしょう (仮想環境を" +"使っている場合はシステムの Python にインストールされた配布物にアクセスできる" +"ようにしておくのを忘れないでください) 。" -#: ../source/guides/modernize-setup-py-project.rst:48 -msgid "Where to start?" -msgstr "どこから始めましょうか？" +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "Windows 版インストーラ" -#: ../source/guides/modernize-setup-py-project.rst:50 +#: ../source/guides/installing-scientific-packages.rst:56 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:" +"Many Python projects that don't (or can't) currently publish wheel files at " +"least publish Windows installers, either on PyPI or on their project " +"download page. Using these installers allows users to avoid the need to set " +"up a suitable environment to build extensions locally." msgstr "" -":term:`プロジェクト ` のソースコードツリーのルート部分には、次に示す" -"ように、 ``[build-system]`` テーブルを含む :file:`pyproject.toml` がなければ" -"なりません:" +"現時点で wheel ファイルを公開していない(または公開できない)多くの Python プロ" +"ジェクトでも、 PyPI 上か、または、そのプロジェクトのダウンロードページで、少" +"なくとも Windows 版インストーラを公開しています。このようなインストーラを使え" +"ば、(他言語)拡張をローカルでビルドするための適切な環境を準備する手間を省くこ" +"とができます。" -#: ../source/guides/modernize-setup-py-project.rst:60 +#: ../source/guides/installing-scientific-packages.rst:61 msgid "" -"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." msgstr "" -"これは、 :term:`ビルドフロントエンド ` にこのプロジェクトの :" -"term:`ビルドバックエンド ` は :ref:`setuptools` だと知らせるた" -"めの標準化されたやり方です。" +"このようなインストーラで用意されている(他言語)拡張は、たいてい、 python.org " +"で公開されている CPython Windows インストーラと互換性のある形で公開されていま" +"す。" -#: ../source/guides/modernize-setup-py-project.rst:63 +#: ../source/guides/installing-scientific-packages.rst:64 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*." +"As with Linux system packages, the Windows installers will only install into " +"a system Python installation - they do not support installation in virtual " +"environments. Allowing access to distributions installed into the system " +"Python when using virtual environments is a common approach to working " +"around this limitation." msgstr "" -"(空のファイルであっても) :file:`pyproject.toml` ファイルが存在していれば、 :" -"ref:`pip` が *ビルド隔離 * を取り扱うデフォルトの動きが変わ" -"ることに注意してください。" - -#: ../source/guides/modernize-setup-py-project.rst:68 -msgid ":ref:`distributing-packages`" -msgstr ":ref:`配布パッケージ `" +"Linux のシステムパッケージの時と同じく、Windows 版インストーラはシステムワイ" +"ドの Python 環境にしかインストールしません -- つまり、仮想環境へのインストー" +"ルはサポートしていないのです。この制約を回避するよくあるやり方は、仮想環境を" +"使っている時にシステムワイドの Python 環境にインストールされた配布物へのアク" +"セスを許可することです。" -#: ../source/guides/modernize-setup-py-project.rst:69 -#: ../source/guides/modernize-setup-py-project.rst:113 -msgid ":ref:`pyproject-build-system-table`" -msgstr ":ref:`pyproject-build-system-table`" +#: ../source/guides/installing-scientific-packages.rst:70 +msgid "" +"The :term:`Wheel` project also provides a :command:`wheel convert` " +"subcommand that can convert a Windows :command:`bdist_wininst` installer to " +"a wheel." +msgstr "" +":term:`Wheel` プロジェクトは、Windows :command:`bdist_wininst` インストーラ" +"を wheel に変換するサブコマンド :command:`wheel convert` も提供しています。" -#: ../source/guides/modernize-setup-py-project.rst:70 -#: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":doc:`pip:reference/build-system/pyproject-toml`" -msgstr ":doc:`pip:reference/build-system/pyproject-toml`" +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +msgstr "macOS インストーラとパッケージマネージャ" -#: ../source/guides/modernize-setup-py-project.rst:74 -msgid "How to handle additional build-time dependencies?" -msgstr "追加的なビルド時の依存関係をどのように扱うのですか？" +#: ../source/guides/installing-scientific-packages.rst:79 +msgid "" +"Similar to the situation on Windows, many projects (including NumPy) publish " +"macOS installers that are compatible with the macOS CPython binaries " +"published on python.org." +msgstr "" +"Windows での状況と同様に、 (NumPy を含む) 多数のプロジェクトは、 python.org " +"で公開される macOS版の Python バイナリと互換性のある macOS 版インストーラを公" +"開しています。" -#: ../source/guides/modernize-setup-py-project.rst:76 +#: ../source/guides/installing-scientific-packages.rst:83 msgid "" -"On top of setuptools itself, if :file:`setup.py` depends on other third-" -"party libraries (outside of Python's standard library), those must be listed " -"in the ``requires`` list of the ``[build-system]`` table, so that the build " -"frontend knows to install them when building the :term:`distributions " -"`." +"macOS users also have access to Linux distribution style package managers " +"such as ``Homebrew``. The SciPy site has more details on using Homebrew to " +"`install SciPy on macOS `_." msgstr "" -"setuptools それ自体の上に、もし :file:`setup.py` が他の (Python の標準ライブ" -"ラリの外側の) 第三者のライブラリに依存しているのであれば、 :term:`配布物 " -"` をビルドする際にビルドフロトンエンドがそれらをインス" -"トールする必要があることを知るために、 ``[build-system]`` テーブルの " -"``require`` リストに挙げられていなければなりません。" +"macOS のユーザは、 ``Homebrew`` のような Linux ディストロスタイルのパッケージ" +"マネージャも使うことができます。ScyPy サイトには、もっと詳しい Homebrew を" +"使って `SciPy を macOS にインストールする `_ 方法の説明があります。" -#: ../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 "例えば、このような :file:`setup.py` ファイルがあれば:" +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "SciPy 配布物" -#: ../source/guides/modernize-setup-py-project.rst:99 +#: ../source/guides/installing-scientific-packages.rst:91 msgid "" -"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " -"unchanged):" +"The SciPy site lists `several distributions `_ that provide the full SciPy stack to end users in an easy " +"to use and update format." msgstr "" -":file:`pyproject.toml` ファイルはこのようであることが要求されます (:file:" -"`setup.py` には変更なし):" - -#: ../source/guides/modernize-setup-py-project.rst:117 -msgid "What is the build isolation feature?" -msgstr "ビルド隔離機能とは何でしょうか？" +"SciPy サイトには、利用・更新が簡単なフォーマットでエンドユーザ向けの SciPy の" +"全機能を提供する `いくつかの配布物 `_ のリストがあります。" -#: ../source/guides/modernize-setup-py-project.rst:119 +#: ../source/guides/installing-scientific-packages.rst:96 msgid "" -"Build frontends typically create an ephemeral virtual environment where they " -"install only the build dependencies (and their dependencies) that are listed " -"under ``build-system.requires`` and trigger the build in that environment." +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." msgstr "" -"典型的な場合、ビルドフロントエンドは、 ``build-system.requires`` の下に列挙さ" -"れているビルド時の依存関係 (と、その依存関係)だけをインストールする先としての" -"一時的な仮想環境を作成し、その環境内でビルドを開始します。" +"これらの配布物の内のいくつかは、標準的な ``pip`` や ``virtualenv`` を基礎にし" +"たツールチェーンと互換性がないかもしれません。" -#: ../source/guides/modernize-setup-py-project.rst:124 +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:808 +msgid "Spack" +msgstr "Spack" + +#: ../source/guides/installing-scientific-packages.rst:101 msgid "" -"For some projects this isolation is unwanted and it can be deactivated as " -"follows:" +"`Spack `_ is a flexible package manager " +"designed to support multiple versions, configurations, platforms, and " +"compilers. It was built to support the needs of large supercomputing centers " +"and scientific application teams, who must often build software many " +"different ways. Spack is not limited to Python; it can install packages for " +"``C``, ``C++``, ``Fortran``, ``R``, and other languages. It is non-" +"destructive; installing a new version of one package does not break existing " +"installations, so many configurations can coexist on the same system." msgstr "" -"この隔離が不要な一部のプロジェクト向けには、以下のようにすれば (隔離を) 非活" -"性化することができます:" +"`Spack `_ は、複数のバージョン・設定・プラッ" +"トフォーム・コンパイラをサポートできるように設計されたパッケージマネージャで" +"す。大規模スーパーコンピュータセンタや科学分野のアプリケーションチームではあ" +"るソフトウェアを異なる方法でビルドする必要が多々ありますが、そのようなニーズ" +"を満たすように作られています。Spack は Python に限らず、 ``C`` ・ ``C++`` ・ " +"``Fortran`` ・ ``R`` やその他のプログラミング言語でも利用できます。Spackは破" +"壊的ではありません; というのは、あるパッケージの新しいバージョンをインストー" +"ルしても先にインストールされたものを壊すことはなく、非常に多くの設定(でインス" +"トールされたもの)が同一システム上で共存できるのです。" -#: ../source/guides/modernize-setup-py-project.rst:126 -msgid "``python -m build --no-isolation``" -msgstr "``python -m build --no-isolation``" +#: ../source/guides/installing-scientific-packages.rst:110 +msgid "" +"Spack offers a simple but powerful syntax that allows users to specify " +"versions and configuration options concisely. Package files are written in " +"pure Python, and they are templated so that it is easy to swap compilers, " +"dependency implementations (like MPI), versions, and build options with a " +"single package file. Spack also generates *module* files so that packages " +"can be loaded and unloaded from the user's environment." +msgstr "" +"Spack は、ユーザがバージョンや設定のオプションを簡潔に表現する単純で力強い文" +"法を提供します。パッケージファイルは純 Python で書かれていて、コンパイラ・ " +"(MPI のような) 依存先の実装・バージョン・ビルドオプションをひとつのパッケージ" +"ファイルの中で容易に入れ替えられるようにテンプレート化されています。Spack " +"は、また、ユーザ環境からあるパッケージをロードしたりしなかったりできるように " +"*modules* ファイルを生成します。" -#: ../source/guides/modernize-setup-py-project.rst:127 -msgid "``python -m pip install --no-build-isolation``" -msgstr "``python -m pip install --no-build-isolation``" +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "conda クロスプラットフォームパッケージマネージャ" -#: ../source/guides/modernize-setup-py-project.rst:135 -msgid "How to handle packaging metadata?" -msgstr "パッケージのメタデータをどのように扱えば良いでしょうか？" +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"`Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use. As of the 5.0 release of " +"Anaconda, about 200 packages are installed by default, and a total of " +"400-500 can be installed and updated from the Anaconda repository." +msgstr "" +"`Anaconda `_ は Anaconda 社が" +"公開した Python 配布物です。Anaconda は、ビッグデータや科学分野で使用する一連" +"のオープンソースソフトウェアの安定版を集めたものです。Anaconda のバージョン " +"5.0 では、デフォルトで約 200 のパッケージがインストールされていて、全部で " +"400-500 が Anaconda リポジトリからインストール可能です。" -#: ../source/guides/modernize-setup-py-project.rst:137 +#: ../source/guides/installing-scientific-packages.rst:127 msgid "" -"All static metadata can optionally be moved to a ``[project]`` table in :" -"file:`pyproject.toml`." +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system included in Anaconda that allows users to " +"install multiple versions of binary software packages and their " +"dependencies, and easily switch between them. It is a cross-platform tool " +"working on Windows, macOS, and Linux. Conda can be used to package up and " +"distribute all kinds of packages, it is not limited to just Python packages. " +"It has full support for native virtual environments. Conda makes " +"environments first-class citizens, making it easy to create independent " +"environments even for C libraries. It is written in Python, but is Python-" +"agnostic. Conda manages Python itself as a package, so that :command:`conda " +"update python` is possible, in contrast to pip, which only manages Python " +"packages. Conda is available in Anaconda and Miniconda (an easy-to-install " +"download with just Python and conda)." msgstr "" -"静的なメタデータはすべて、 :file:`pyproject.toml` の ``[project]`` テーブルへ" -"移しても構いません。" +"``conda`` は、複数のバージョンのソフトウェアのバイナリパッケージやその依存先" +"パッケージをインストールして容易に切り替えて使えるようにする Anaconda に含ま" +"れる (BSDライセンスの) オープンソースのパッケージマネジメントシステム兼環境管" +"理システムです。(これは) Windows・MacOS・Linuxで動作するクロスプラットフォー" +"ムのツールです。conda を使えば、Python のパッケージに限らず、あらゆる種類の" +"パッケージをまとめたり配布したりできます。Python に組み込まれた仮想環境を完全" +"にサポートしています。 C 言語で書かれたライブラリさえも容易に独立した環境を生" +"成できるようにすることで、conda は(仮想)環境を制限なく使えるもの(第１級オブ" +"ジェクト)にしています。Python で書かれていていますが、Pythonに依存しているわ" +"けではありません。conda は Python そのものをパッケージのひとつとして扱うた" +"め :command:`conda update python` とすることが可能で、Python のパッケージだけ" +"を扱う pip とは対照的です。conda は Anaconda や Miniconda (Python と conda が" +"動作するだけの最小版のAnacoda) から手に入ります。" -#: ../source/guides/modernize-setup-py-project.rst:151 -msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +#: ../source/guides/installing-stand-alone-command-line-tools.rst:2 +msgid "Installing stand alone command line tools" +msgstr "スタンドアローンのコマンドラインツールをインストールする" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." msgstr "" -"このように :file:`pyproject.toml` ファイルで完全に置き換えることも可能です:" +"多くのパッケージは、コマンドラインアプリケーションを提供しています。そのよう" +"なパッケージの例としては、 `mypy `_ ・ " +"`flake8 `_ ・ `black `_ ・ :ref:`pipenv` が挙げられます。" -#: ../source/guides/modernize-setup-py-project.rst:164 +#: ../source/guides/installing-stand-alone-command-line-tools.rst:10 msgid "" -"Read :ref:`pyproject-project-table` for the full specification of the " -"content allowed in the ``[project]`` table." +"Usually you want to be able to access these applications from anywhere on " +"your system, but installing packages and their dependencies to the same " +"global environment can cause version conflicts and break dependencies the " +"operating system has on Python packages." msgstr "" -"``[project]`` テーブルで許される内容の完全な仕様については、 :ref:" -"`` を読んでください。" - -#: ../source/guides/modernize-setup-py-project.rst:169 -msgid "How to handle dynamic metadata?" -msgstr "動的なメタデータをどのように取り扱いますか？" +"通常ならシステムのどこからでもこれらのアプリケーションにアクセスできるように" +"したいと思うでしょうが、パッケージとその依存先パッケージを同じグローバル環境" +"にインストールすると、バージョンの衝突を起こしてオペレーティングシステムが" +"持っている Python パッケージ間の依存関係を破壊してしまうかもしれません。" -#: ../source/guides/modernize-setup-py-project.rst:171 +#: ../source/guides/installing-stand-alone-command-line-tools.rst:15 msgid "" -"If some packaging metadata fields are not static they need to be listed as " -"``dynamic`` in this ``[project]`` table." +":ref:`pipx` solves this by creating a virtual environment for each package, " +"while also ensuring that its applications are accessible through a directory " +"that is on your ``$PATH``. This allows each package to be upgraded or " +"uninstalled without causing conflicts with other packages, and allows you to " +"safely run the applications from anywhere." msgstr "" -"パッケージングであるメタデータフィールドが静的ではないならば、 ``[project]`` " -"テーブルの ``dynamic`` に列挙する必要があります。" +":ref:`pipx` は、 ``$PATH`` に含まれるディレクトリを通してアプリケーションにア" +"クセスできるようにしつつ各パッケージに仮想環境を作成することでこの問題を解決" +"します。こうすることで、各パッケージの更新や削除をしても他のパッケージには影" +"響を与えず、どこからでもアプリケーションを安全に走らせることができるようにで" +"きます。" -#: ../source/guides/modernize-setup-py-project.rst:191 -msgid "can be modernized as follows:" -msgstr "以下のように近代化することができるでしょう:" +#: ../source/guides/installing-stand-alone-command-line-tools.rst:21 +msgid "pipx only works with Python 3.6+." +msgstr "pipx は Python 3.6+ でのみ動作します。" -#: ../source/guides/modernize-setup-py-project.rst:223 -msgid ":ref:`declaring-project-metadata-dynamic`" -msgstr "" -":ref:`プロジェクトのメタデータを動的であると宣言する `" +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx is installed with pip:" +msgstr "pipx は pip と一緒にインストールされています:" -#: ../source/guides/modernize-setup-py-project.rst:227 -msgid "What if something that can not be changed expects a ``setup.py`` file?" +#: ../source/guides/installing-stand-alone-command-line-tools.rst:41 +msgid "" +"``ensurepath`` ensures that the application directory is on your ``$PATH``. " +"You may need to restart your terminal for this update to take effect." msgstr "" -"変更不能ななにかが ``setup.py`` ファイルがあるものと期待していたらどうします" -"か？" +"``ensurepath `` は、アプリケーションのあるディレクトリが ``$PATH`` に含まれる" +"ようにすることを保証します。この更新(訳注、``$PATH``の修正のこと)が効果を持つ" +"ようにするためにターミナルを再起動する必要があるかもしれません。" -#: ../source/guides/modernize-setup-py-project.rst:229 +#: ../source/guides/installing-stand-alone-command-line-tools.rst:44 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``." +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." msgstr "" -"例えば、簡単には変更することができないプロセスが存在していて、それが " -"``python setup.py --name`` のようなコマンドの実行を必要としてる場合。" +"これで、 ``pipx install`` を使ってパッケージをインストールすることができるよ" +"うになり、どこからでもそのパッケージのアプリケーションを起動することができる" +"ようになりました。" -#: ../source/guides/modernize-setup-py-project.rst:232 +#: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "例:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:74 msgid "" -"It is perfectly fine to leave a :file:`setup.py` file in the project source " -"tree even after all its content has been moved to :file:`pyproject.toml`. " -"This file can be as minimalistic as this:" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" msgstr "" -"たとえ全ての内容が :file:`pyproject.toml` へ移された後であっても、プロジェク" -"トのソースコードツリーに `setup.py` を残すことは完全に問題のないことです。こ" -"のファイルの最小限の姿はこのようになります:" - -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`pyproject-toml-spec`" -msgstr ":ref:`pyproject-toml-spec`" +"pipx でインストールされたパッケージのリストやどんなアプリケーションが使用可能" +"かを見るためには、 ``pipx list`` を使ってください:" -#: ../source/guides/modernize-setup-py-project.rst:248 -msgid ":doc:`setuptools:build_meta`" -msgstr ":doc:`setuptools:build_meta`" +#: ../source/guides/installing-stand-alone-command-line-tools.rst:98 +msgid "To upgrade or uninstall a package:" +msgstr "パッケージを更新またはアンインストールするには:" -#: ../source/guides/multi-version-installs.rst:6 -msgid "Multi-version installs" -msgstr "複数バージョンのインストール" +#: ../source/guides/installing-stand-alone-command-line-tools.rst:105 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "pipx は pip を使って更新やアンインストールができます:" -#: ../source/guides/multi-version-installs.rst:11 +#: ../source/guides/installing-stand-alone-command-line-tools.rst:121 msgid "" -"easy_install allows simultaneous installation of different versions of the " -"same project into a single environment shared by multiple programs which " -"must ``require`` the appropriate version of the project at run time (using " -"``pkg_resources``)." +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" msgstr "" -"easy_install を使えば、異なるバージョンの同一プロジェクトをひとつの環境に同時" -"にインストールして、なおかつ、それぞれ動作時にプロジェクトの特定のバージョン" -"を (``pkg_resources`` での指定を通じて) ``要求 `` する複数のプログラ" -"ムをその環境で動作させることができます。" +"また、pipx ならアプリケーションの最新版を一時的で短命の環境にインストールして" +"動作させることができます。例えば:" -#: ../source/guides/multi-version-installs.rst:16 -msgid "" -"For many use cases, virtual environments address this need without the " -"complication of the ``require`` directive. However, the advantage of " -"parallel installations within the same environment is that it works for an " -"environment shared by multiple applications, such as the system Python in a " -"Linux distribution." +#: ../source/guides/installing-stand-alone-command-line-tools.rst:128 +msgid "To see the full list of commands pipx offers, run:" msgstr "" -"多くのユースケースでは、 ``require`` ディレクティブを混乱させる事なく、仮想環" -"境がこのような需要を満たします。しかしながら、同一環境内に(複数バージョンを)" -"並行してインストールすることの利点は、Linux 配布物におけるシステム側の " -"Python のように、複数のアプリケーションによって共有される環境で動作することで" -"す。" +"pipx で使える(サブ)コマンドの完全なリストを見たければ、次のようにしてくださ" +"い:" -#: ../source/guides/multi-version-installs.rst:22 -msgid "" -"The major limitation of ``pkg_resources`` based parallel installation is " -"that as soon as you import ``pkg_resources`` it locks in the *default* " -"version of everything which is already available on sys.path. This can cause " -"problems, since ``setuptools`` created command line scripts use " -"``pkg_resources`` to find the entry point to execute. This means that, for " -"example, you can't use ``require`` tests invoked through ``nose`` or a WSGI " -"application invoked through ``gunicorn`` if your application needs a non-" -"default version of anything that is available on the standard ``sys.path`` - " -"the script wrapper for the main application will lock in the version that is " -"available by default, so the subsequent ``require`` call in your own code " -"fails with a spurious version conflict." +#: ../source/guides/installing-stand-alone-command-line-tools.rst:134 +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" msgstr "" -"並行インストールに立脚した ``pkg_resources`` の主要な制限事項は、 " -"``pkg_resources`` をインポートするや否や、sys.path 上で既に利用可能なものはす" -"べてそのバージョンに *デフォルト* バージョンが固定されてしまうことです。コマ" -"ンドラインスクリプトで生成された ``setuptools`` が ``pkg_resources`` を使って" -"プログラム実行のためのエントリポイントを探索するので、これは問題を引き起こす" -"かもしれません。これが意味するところは、例えば、そのアプリケーションが、標準" -"の ``sys.path`` 上に存在するものなら何であれ、それとは異なるバージョンを必要" -"とする場合に、 ``nose`` を通じて ``require`` テストを使ったり ``gunicorn`` を" -"通じて WSGI アプリケーションを呼び出したりすることができない - メインのアプリ" -"ケーションのためのスクリプトラッパがデフォルトで利用可能なバージョンに固定さ" -"れてしまって、各アプリケーションの引き続く ``require`` 呼び出しが見せかけの" -"バージョン衝突によって失敗してしまう、ということです。" +"Linux パッケージマネージャを使って pip/setuptools/wheel をインストールする" -#: ../source/guides/multi-version-installs.rst:34 +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "2021-07-26" + +#: ../source/guides/installing-using-linux-tools.rst:10 msgid "" -"This can be worked around by setting all dependencies in ``__main__." -"__requires__`` before importing ``pkg_resources`` for the first time, but " -"that approach does mean that standard command line invocations of the " -"affected tools can't be used - it's necessary to write a custom wrapper " -"script or use ``python3 -c ''`` to invoke the application's main " -"entry point directly." +"This section covers how to install :ref:`pip`, :ref:`setuptools`, and :ref:" +"`wheel` using Linux package managers." msgstr "" -"最初に ``pkg_resources`` をインポートするよりも前に ``__main__." -"__requires__`` の中のすべての依存関係を設定しておくことでこの問題を回避するこ" -"とができますが、このアプローチでは影響を受けるツールを標準のコマンドラインか" -"らの呼び出しで使うことができないことになります - つまり、独自のラッパスクリプ" -"トを書くか、アプリケーションの main エントリポイントを直接に呼び出すための " -"``python -c ''`` を使うかしなければなりません。" +"この節では、Linux のパッケージマネージャを使って :ref:`pip` ・ :ref:" +"`setuptools` ・ :ref:`wheel` をインストールする方法について説明します。" -#: ../source/guides/multi-version-installs.rst:41 +#: ../source/guides/installing-using-linux-tools.rst:13 msgid "" -"Refer to the `pkg_resources documentation `__ for more details." +"If you're using a Python that was downloaded from `python.org `_, then this section does not apply. See the :ref:" +"`installing_requirements` section instead." msgstr "" -"さらに詳しい情報については、 `pkg_resources 説明文書 `__ を参照して" -"ください。" - -#: ../source/guides/packaging-binary-extensions.rst:5 -msgid "Packaging binary extensions" -msgstr "バイナリ拡張をパッケージングする" - -#: ../source/guides/packaging-binary-extensions.rst:8 -msgid "2013-12-08" -msgstr "2013-12-08" +"`python.org `_ からダウンロードした Python を使ってい" +"るなら、この節の議論はあてはまりません。代わりに :ref:" +"`installing_requirements` 節を見てください。" -#: ../source/guides/packaging-binary-extensions.rst:10 +#: ../source/guides/installing-using-linux-tools.rst:17 msgid "" -"One of the features of the CPython reference interpreter is that, in " -"addition to allowing the execution of Python code, it also exposes a rich C " -"API for use by other software. One of the most common uses of this C API is " -"to create importable C extensions that allow things which aren't always easy " -"to achieve in pure Python code." +"Note that it's common for the versions of :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` supported by a specific Linux Distribution to be outdated " +"by the time it's released to the public, and updates generally only occur " +"for security reasons, not for feature updates. For certain Distributions, " +"there are additional repositories that can be enabled to provide newer " +"versions. The repositories we know about are explained below." msgstr "" -"CPython の参照インタープリタの機能の一つは、Python のコードを実行することに加" -"えて、他のソフトウェアによる利用のために豊富な C の API を露出することです。" -"この C の API の最もよくある利用方法は、純粋な Python のコードでは必ずしも簡" -"単には達成できないようなことをインポート可能な C 拡張として作成することです。" +"特定の Linux ディストロでサポートされているバージョンの :ref:`pip` ・ :ref:" +"`setuptools` ・ :ref:`wheel` が公開時点で既に旧バージョンになってしまっている" +"のに、更新されるのはセキュリティが理由の時だけで機能追加があっても更新されな" +"い、というのはよくあることです。ディストロの中にはより新しいバージョンを提供" +"することができる追加のリポジトリが存在する場合もあります。以下では、そのよう" +"なリポジトリのうちの既知のものを説明します。" -#: ../source/guides/packaging-binary-extensions.rst:18 -msgid "An overview of binary extensions" -msgstr "バイナリ拡張の概要" +#: ../source/guides/installing-using-linux-tools.rst:24 +msgid "" +"Also note that it's somewhat common for Distributions to apply patches for " +"the sake of security and normalization to their own standards. In some " +"cases, this can lead to bugs or unexpected behaviors that vary from the " +"original unpatched versions. When this is known, we will make note of it " +"below." +msgstr "" +"また、ディストロがセキュリティ上の理由やディストロ自身の標準に合致させる目的" +"でパッチを適用することはそれなりによくあります。いくつかのケースでは、オリジ" +"ナルの未パッチのバージョンとは異なるバグや期待に反した動きにつながることもあ" +"ります。わかっているものについては、以下に注記します。" -#: ../source/guides/packaging-binary-extensions.rst:21 -msgid "Use cases" -msgstr "ユースケース" +#: ../source/guides/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" -#: ../source/guides/packaging-binary-extensions.rst:23 +#: ../source/guides/installing-using-linux-tools.rst:37 msgid "" -"The typical use cases for binary extensions break down into just three " -"conventional categories:" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." msgstr "" -"バイナリ拡張の典型的なユースケースは、たった３個の伝統的なカテゴリに分類され" -"ます:" +"Fedora における Python についてもっと学ぶには、 `official Fedora docs`_ ・ " +"`Python Classroom`_ ・ `Fedora Loves Python`_ を見てください。" -#: ../source/guides/packaging-binary-extensions.rst:26 +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "CentOS/RHEL" + +#: ../source/guides/installing-using-linux-tools.rst:47 msgid "" -"**accelerator modules**: these modules are completely self-contained, and " -"are created solely to run faster than the equivalent pure Python code runs " -"in CPython. Ideally, accelerator modules will always have a pure Python " -"equivalent to use as a fallback if the accelerated version isn't available " -"on a given system. The CPython standard library makes extensive use of " -"accelerator modules. *Example*: When importing ``datetime``, Python falls " -"back to the `datetime.py `_ module if the C implementation ( `_datetimemodule.c `_) is not " -"available." +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." msgstr "" -"**アクセラレータモジュール**: これらのモジュールは完全に自己完結型で、" -"CPython で同機能の純粋なPython コードを走らせるよりも速く動作するためにだけ作" -"成されます。アクセラレートされたバージョンが当該システム上で動作しなかった時" -"のために、アクセラレータモジュールには同機能の純粋なPythonのコードを予備品と" -"して同梱していることが理想的です。CPython の標準ライブラリはアクセラレータモ" -"ジュールを多用しています。*例*: ``datetime`` をインポートする際、C での実装 " -"(`_datetimemodule.c `_) が使えない時には、`datetime.py `_ にフォールバックします。" +"CentOS と RHEL は、そのコアリポジトリでは :ref:`pip` や :ref:`wheel` を提供し" +"ていませんが、 :ref:`setuptools` はデフォルトでインストールされます。" -#: ../source/guides/packaging-binary-extensions.rst:37 -msgid "" -"**wrapper modules**: these modules are created to expose existing C " -"interfaces to Python code. They may either expose the underlying C interface " -"directly, or else expose a more \"Pythonic\" API that makes use of Python " -"language features to make the API easier to use. The CPython standard " -"library makes extensive use of wrapper modules. *Example*: `functools.py " -"`_ is a Python " -"module wrapper for `_functoolsmodule.c `_." +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" msgstr "" -"**ラッパモジュール**: これらのモジュールは、既存の C のインタフェースを " -"Python に見せるために作られます。それらは C のインタフェースを直接に見せる" -"か、または、Python 言語の機能を使ってAPI をより使いやすくするようなもっと " -"\"Pythonic\" なやり方で見せるかします。CPython の標準ライブラリでは、ラッパモ" -"ジュールを多用しています。 *例*: `functools.py `_ は、 `_functoolsmodule.c `_ のための" -"ラッパモジュールです。" +"システムに付属の Python 用に pip や wheel をインストールするには、二つのやり" +"方があります:" -#: ../source/guides/packaging-binary-extensions.rst:45 +#: ../source/guides/installing-using-linux-tools.rst:52 msgid "" -"**low-level system access**: these modules are created to access lower level " -"features of the CPython runtime, the operating system, or the underlying " -"hardware. Through platform specific code, extension modules may achieve " -"things that aren't possible in pure Python code. A number of CPython " -"standard library modules are written in C in order to access interpreter " -"internals that aren't exposed at the language level. *Example*: ``sys``, " -"which comes from `sysmodule.c `_." +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and " +"wheel like so:" msgstr "" -"**低レベルシステムアクセス**: これらのモジュールは、CPython ランタイムやオペ" -"レーティングシステム、あるいはさらに下層のハードウェアの低レベルの機能にアク" -"セスするために作成されています。プラットフォームに固有のコードを通して、純粋" -"な Python コードでは不可能なことを拡張モジュールが達成できるかもしれません。" -"結構な数の CPython の標準ライブラリモジュールが C で書かれていて、言語のレベ" -"ルには提供されていないようなインタープリタの内部にアクセスできるようになって" -"います。 *例*: ``sys`` は `sysmodule.c `_ から来ています。" +"`これらの指示 `__ に従って `EPEL リポジトリ `_ を有効にしてください。 EPEL 7 では、pip と " +"wheel をこんなふうにインストールできます:" -#: ../source/guides/packaging-binary-extensions.rst:54 +#: ../source/guides/installing-using-linux-tools.rst:61 msgid "" -"One particularly notable feature of C extensions is that, when they don't " -"need to call back into the interpreter runtime, they can release CPython's " -"global interpreter lock around long-running operations (regardless of " -"whether those operations are CPU or IO bound)." +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." msgstr "" -"C 言語拡張の特筆すべき機能は、インタプリタランタイムにコールバックする必要の" -"ない時には、 (CPU制約であろうとIO制約であろうと関わりなく) 長時間走り続ける操" -"作を包む CPython グローバルインタプリタロックを解放することができるということ" -"です。" +"EPEL はシステムに欠けていて衝突しないパッケージだけを提供しているので、コアリ" +"ポジトリに入っている setuptools は EPEL にはありません。" -#: ../source/guides/packaging-binary-extensions.rst:59 +#: ../source/guides/installing-using-linux-tools.rst:65 msgid "" -"Not all extension modules will fit neatly into the above categories. The " -"extension modules included with NumPy, for example, span all three use cases " -"- they move inner loops to C for speed reasons, wrap external libraries " -"written in C, FORTRAN and other languages, and use low level system " -"interfaces for both CPython and the underlying operation system to support " -"concurrent execution of vectorised operations and to tightly control the " -"exact memory layout of created objects." +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" msgstr "" -"必ずしも全ての拡張モジュールが上記のカテゴリにぴたりと当て嵌まる訳ではありま" -"せん。例えば NumPy に含まれる拡張モジュールは３個のカテゴリのすべてにまたがっ" -"ています - 動作速度上の理由から内側のループを C 言語に移しているし、C 言語や " -"FORTRAN 言語その他で書かれた外部のライブラリをラップしているし、また、ベクタ" -"演算の並列実行や生成したオブジェクトのメモリレイアウトを正確な管理のために、 " -"CPython とその下にあるオペレーティングシステムの両方の低レベルなシステムイン" -"ターフェイスを利用しています。" +"`これらの指示 `__ [1]_ に従って `PyPA Copr Repo `_ を有効にしてください。 pip と wheel はこうやってイン" +"ストールできます:" -#: ../source/guides/packaging-binary-extensions.rst:69 -msgid "Disadvantages" -msgstr "欠点" +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "さらに setuptools を更新するには、次のようにしてください:" -#: ../source/guides/packaging-binary-extensions.rst:71 +#: ../source/guides/installing-using-linux-tools.rst:81 msgid "" -"The main disadvantage of using binary extensions is the fact that it makes " -"subsequent distribution of the software more difficult. One of the " -"advantages of using Python is that it is largely cross platform, and the " -"languages used to write extension modules (typically C or C++, but really " -"any language that can bind to the CPython C API) typically require that " -"custom binaries be created for different platforms." +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" msgstr "" -"バイナリ拡張を使うことの主たる欠点は、引き続くソフトウェア配布がより難しくな" -"ることです。Python を使う利点のひとつは非常に広範囲のクロスプラットフォームで" -"ある (訳注、同一の Python コードが広範囲の異種プラットフォームで動作する) こ" -"とですが、拡張モジュールを書くのに使われる言語 (典型的には C 言語や C++ だ" -"が、実際にはどんな言語でも CPython の C 言語 API にバインドできる) は異なるプ" -"ラットフォームには異なるバイナリを作成しなければならないのが普通なのです。" - -#: ../source/guides/packaging-binary-extensions.rst:78 -msgid "This means that binary extensions:" -msgstr "これが意味するところは、バイナリ拡張は:" +"システムの環境とは別に (yum を使って) pip ・ wheel ・ setuptools をインストー" +"ルするには、ふたつのやり方があります:" -#: ../source/guides/packaging-binary-extensions.rst:80 +#: ../source/guides/installing-using-linux-tools.rst:85 msgid "" -"require that end users be able to either build them from source, or else " -"that someone publish pre-built binaries for common platforms" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." msgstr "" -"エンドユーザがソースコードからビルドできるか、または、誰かが共通のプラット" -"フォーム向けにビルド済みのバイナリを公開するか、のいずれかでなければなりませ" -"ん" +"pip ・ setuptools ・ wheel を含むコレクションを (システムとは) 並行に有効化し" +"て \"ソフトウェアコレクション\" 機能を使ってください。" -#: ../source/guides/packaging-binary-extensions.rst:83 +#: ../source/guides/installing-using-linux-tools.rst:88 msgid "" -"may not be compatible with different builds of the CPython reference " -"interpreter" -msgstr "CPython 参照インタプリタのビルドが異なると互換性がないかもしれません" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" +"Red Hat についてはこちらを見てください: https://developers.redhat.com/" +"products/softwarecollections/overview" -#: ../source/guides/packaging-binary-extensions.rst:86 -msgid "" -"often will not work correctly with alternative interpreters such as PyPy, " -"IronPython or Jython" +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "CentOS の場合は、こちらを見てください: https://github.com/sclorg" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." msgstr "" -"PyPy ・ IronPython ・ Jython のような代替インタプリタ上では動作しないことがし" -"ばしばです" +"コレクションに含まれているバージョンが最新版であるとは限らない点に注意してく" +"ださい。" -#: ../source/guides/packaging-binary-extensions.rst:89 +#: ../source/guides/installing-using-linux-tools.rst:94 msgid "" -"if handcoded, make maintenance more difficult by requiring that maintainers " -"be familiar not only with Python, but also with the language used to create " -"the binary extension, as well as with the details of the CPython C API." +"Enable the `IUS repository `_ and install one of the " +"`parallel-installable `_ " +"Pythons, along with pip, setuptools, and wheel, which are kept fairly up to " +"date." msgstr "" -"もしハードコードされているなら、メンテナンス担当者が Python のみならずそのバ" -"イナリ拡張を作成するために使われている言語についてもCPython の C 言語 API に" -"ついても慣れ親しんでいることが要求されるので、メンテナンスがより難しくなるで" -"しょう。" +"`IUS リポジトリ `_ を有効にして、かなり最新版に近い状態" +"に維持されている pip ・ setuptools ・ wheel と一緒に `並列インストール可能 " +"`_ な Python の内のひとつ" +"をインストールしてください。" -#: ../source/guides/packaging-binary-extensions.rst:94 +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "例えば、CentOS7/RHEL7 での Python 3.4 については:" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "openSUSE" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "Debian/Ubuntu とその派生物" + +#: ../source/guides/installing-using-linux-tools.rst:120 +msgid "Firstly, update and refresh repository lists by running this command:" +msgstr "" +"第一に、このコマンドを実行してリポジトリリストを更新し情報を新しくしてくださ" +"い。" + +#: ../source/guides/installing-using-linux-tools.rst:129 msgid "" -"if a pure Python fallback implementation is provided, make maintenance more " -"difficult by requiring that changes be implemented in two places, and " -"introducing additional complexity in the test suite to ensure both versions " -"are always executed." +"Recent Debian/Ubuntu versions have modified pip to use the `\"User Scheme\" " +"`_ by default, " +"which is a significant behavior change that can be surprising to some users." msgstr "" -"純粋な Python で書かれた退避先実装が用意されているなら、変更を実装するべき場" -"所が２箇所になるのと、両方の実装が常に実行されることを保証するテストスイート" -"を準備するために複雑さが増加することになるので、メンテナンスがより一層困難に" -"なります。" +"最近のバージョンの Debian/Ubuntu は、 pip がデフォルトで `\"User Scheme\" " +"`_ を使うように修正" +"されていますが、これはユーザの一部を驚かせるような重要な動作の変更に当たるで" +"しょう。" -#: ../source/guides/packaging-binary-extensions.rst:99 +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "Arch Linux" + +#: ../source/guides/installing-using-linux-tools.rst:143 msgid "" -"Another disadvantage of relying on binary extensions is that alternative " -"import mechanisms (such as the ability to import modules directly from " -"zipfiles) often won't work for extension modules (as the dynamic loading " -"mechanisms on most platforms can only load libraries from disk)." +"Currently, there is no \"copr\" yum plugin available for CentOS/RHEL, so the " +"only option is to manually place the repo files as described." msgstr "" -"バイナリ拡張に依存することによるさらなる欠点は、 (例えば zip ファイルから直接" -"にインポートする能力など) 通常とは異なるインポート機構が、しばしば拡張モ" -"ジュールでは動作しない (ほとんどのプラットフォームでは動的ロード機構はディス" -"クからライブラリを読み込むことしかできないため) ということです。" +"現時点では、 CentOS/RHEL には yum プラグインの \"copr\" が存在しないので、後" +"述するように手動でリポジトリファイルを配置するしかありません。" -#: ../source/guides/packaging-binary-extensions.rst:106 -msgid "Alternatives to handcoded accelerator modules" -msgstr "ハードコードされたアクセラレータモジュールの代わりとなるもの" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "pip と venv を使って仮想環境にパッケージをインストールする" -#: ../source/guides/packaging-binary-extensions.rst:108 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 msgid "" -"When extension modules are just being used to make code run faster (after " -"profiling has identified the code where the speed increase is worth " -"additional maintenance effort), a number of other alternatives should also " -"be considered:" +"This guide discusses how to create and activate a virtual environment using " +"the standard library's virtual environment tool :ref:`venv` and install " +"packages. The guide covers how to:" msgstr "" -"拡張モジュールが単純にプログラムを速く走らせるためだけに使われてい (て、プロ" -"ファイリングの結果、メンテナンス工数が増えることを甘受しても速度を上げること" -"に価値があると判断され) る時には、他の複数の選択肢も検討しておくべきです:" +"このガイド文書では、標準ライブラリの仮想環境ツール :ref:`venv` を使って仮想環" +"境を作成し活性化する方法と、パッケージをインストールする方法について議論しま" +"す。このガイド文書は次のようなことを行う方法をカバーします:" -#: ../source/guides/packaging-binary-extensions.rst:113 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:8 +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:153 +msgid "Prepare pip" +msgstr "pip の準備をする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "``pip`` コマンドを使って仮想環境にパッケージをインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "requirements ファイルを使う、作成する" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 msgid "" -"look for existing optimised alternatives. The CPython standard library " -"includes a number of optimised data structures and algorithms (especially in " -"the builtins and the ``collections`` and ``itertools`` modules). The Python " -"Package Index also offers additional alternatives. Sometimes, the " -"appropriate choice of standard library or third party module can avoid the " -"need to create your own accelerator module." +"This guide applies to supported versions of Python, currently 3.8 and higher." msgstr "" -"既存の最適化された代替策を探す。CPython の標準ライブラリには、最適化された" -"データ構造やアルゴリズム (特に組み込み済みのものや ``collections`` および " -"``itertools`` モジュール) が多数含まれています。Python パッケージインデックス" -"にも他の代替となるパッケージがあります。時には、標準ライブラリや第三パーティ" -"のモジュールから適切なものを選択することで、自分自身でアクセラレータパッケー" -"ジを作成する必要に迫られないで済むでしょう。" +"このガイド文書は、サポートされている Python のバージョン、現時点では 3.8 およ" +"びこれ以降のものに適用されます。" -#: ../source/guides/packaging-binary-extensions.rst:120 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 msgid "" -"for long running applications, the JIT compiled `PyPy interpreter `__ may offer a suitable alternative to the standard CPython " -"runtime. The main barrier to adopting PyPy is typically reliance on other " -"binary extension modules - while PyPy does emulate the CPython C API, " -"modules that rely on that cause problems for the PyPy JIT, and the emulation " -"layer can often expose latent defects in extension modules that CPython " -"currently tolerates (frequently around reference counting errors - an object " -"having one live reference instead of two often won't break anything, but no " -"references instead of one is a major problem)." +"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 "" -"長時間に渡って走り続けるアプリケーションに対しては、標準の CPython ランタイム" -"の代わりに JIT コンパイルされた `PyPy インタープリタ `__ を使うことが適切な代替策となるかもしれません。 PyPy を適用しようとする" -"時、典型的には他のバイナリ拡張モジュールへの依存が主たる障害になります - " -"PyPy が CPython の C 言語 API をエミュレートする一方で、その API に依存するモ" -"ジュールの側が PyPy の JIT に問題を引き起こし、また、エミュレーション層が " -"CPython では現在は許容されているような拡張モジュール側の潜在的な瑕疵 (参照カ" -"ウントに関係するエラーであることが多い - あるオブジェクトへの参照が２個あるは" -"ずのところが１個しかないという状態は何も悪さをしませんが、１個の参照のはずが" -"参照なしとなる場合が主な問題になります) をしばしば暴露してしまうのです。" +"この文書では、 **パッケージ** という用語を通常は外部のホストからインストール" +"される :term:`配布パッケージ ` の意味で使います。これ" +"は Python ソースコードでモジュールをインポートするという意味で使われる :term:" +"`インポートパッケージ ` とは異なります。" -#: ../source/guides/packaging-binary-extensions.rst:130 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 msgid "" -"`Cython `__ is a mature static compiler that can " -"compile most Python code to C extension modules. The initial compilation " -"provides some speed increases (by bypassing the CPython interpreter layer), " -"and Cython's optional static typing features can offer additional " -"opportunities for speed increases. Using Cython still carries the " -"`disadvantages`_ associated with using binary extensions, but has the " -"benefit of having a reduced barrier to entry for Python programmers " -"(relative to other languages like C or C++)." +"This guide has the prerequisite that you are using an official Python " +"version obtained from . If you are using " +"your operating system's package manager to install Python, please ensure " +"that Python is installed before proceeding with these steps." msgstr "" -"`Cython `__ は、ほとんどの Python コードを C 言語の拡張" -"モジュールに変換できる成熟した静的コンパイラです。当初のコンパイルでは、" -"(CPython のインタプリタ層をバイパスすることによって) いくらかの速度向上が見込" -"めるとともに、 Cython のオプション扱いの静的型付け機能によってさらに速度向上" -"の機会があるかもしれません。Cython の使用には、バイナリ拡張の使用に関連した `" -"欠点`_ がまだ残っていますが、Python プログラマにとって (C 言語や C++ のような" -"他言語に比べると) 参入障壁が低いという利点があります。" +"このガイド文書は、 から取得する公式の " +"Python を使っていることを前提条件にしています。Python をインストールするのに" +"オペレーティングシステムのパッケージマネージャを使っているのであれば、ここに" +"述べるようなステップを進める前に、Python がインストールされていることを確実に" +"してください。" -#: ../source/guides/packaging-binary-extensions.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:32 +msgid "Create and Use Virtual Environments" +msgstr "仮想環境を構築し使用する" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:35 +msgid "Create a new virtual environment" +msgstr "新しい仮想環境を作成する" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:37 msgid "" -"`Numba `__ is a newer tool, created by members of " -"the scientific Python community, that aims to leverage LLVM to allow " -"selective compilation of pieces of a Python application to native machine " -"code at runtime. It requires that LLVM be available on the system where the " -"code is running, but can provide significant speed increases, especially for " -"operations that are amenable to vectorisation." +":ref:`venv` (for Python 3) allows you to manage separate package " +"installations for different projects. It creates a \"virtual\" isolated " +"Python installation. When you switch projects, you can create a new virtual " +"environment which is isolated from other virtual environments. You benefit " +"from the virtual environment since packages can be installed confidently and " +"will not interfere with another project's environment." msgstr "" -"`Numba `__ は新しめのツールで、LLVM を活用して " -"Python アプリケーションの一部分をランタイムに選択的にネイティブの機械コードに" -"コンパイルできるようにすることを目指している科学分野の Python コミュニティに" -"よって作成されました。この取り組みでは、コードが動作するシステムに LLVM が存" -"在していなければなりませんが、特にベクトル化が容易な操作について顕著な速度増" -"加を提供することができます。" +":ref:`venv` (Python 3 用) を使うと、異なるプロジェクトにそれぞれ別のパッケー" +"ジをインストールして管理できます。(仮想環境は) 互いに影響を与えない\"仮想的な" +"\" Python インストール環境を生成します。別のプロジェクトに移動すると、他の仮" +"想環境から隔離された新しい仮想環境を作成することができます。仮想環境を使うこ" +"とで、パッケージ群を自信を持ってインストールすることができ、他のプロジェクト" +"の環境には干渉しないであろうことから、あなたは利益を得ることができます。" -#: ../source/guides/packaging-binary-extensions.rst:148 -msgid "Alternatives to handcoded wrapper modules" -msgstr "ハードコードされたラッパモジュールに対する代替策" +#: ../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 "第三者のパッケージ群を使う時には仮想環境を用いることが推奨されます。" -#: ../source/guides/packaging-binary-extensions.rst:150 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"The C ABI (Application Binary Interface) is a common standard for sharing " -"functionality between multiple applications. One of the strengths of the " -"CPython C API (Application Programming Interface) is allowing Python users " -"to tap into that functionality. However, wrapping modules by hand is quite " -"tedious, so a number of other alternative approaches should be considered." +"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 "" -"C 言語 ABI (アプリケーションバイナリインタフェイス )は、複数のアプリケーションの間で機能を共有する上での一般的な標準で" -"す。CPython の C 言語 API (アプリケーションプログラミングインタフェイス " -") を使えば Python のユーザがその機能に入り" -"込むことができます。しかしながら、手動でモジュールごとにラッピングしていくの" -"はうんざりするような作業なので、いくつもの代替アプローチが検討されるべきで" -"す。" +"仮想環境を作成するには、プロジェクトのディレクトリへ行って次のようなコマンド" +"を実行してください。これによって、ローカルの ``.venv`` フォルダに新しい仮想環" +"境ができるでしょう:" -#: ../source/guides/packaging-binary-extensions.rst:156 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" -"The approaches described below don't simplify the distribution case at all, " -"but they *can* significantly reduce the maintenance burden of keeping " -"wrapper modules up to date." +"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 "" -"以下に記述するアプローチは、単に配布物での事例ということは全くなく、むしろ" -"ラッパモジュールを最新に保つというメンテナンス上の重荷を大いに軽減することが" -"できるものです。" +"二つ目の引数は、仮想環境を作成するべき場所の指定です。一般的には、プロジェク" +"トのルートディレクトリに ``.venv`` という名前で作成します。" -#: ../source/guides/packaging-binary-extensions.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" -"In addition to being useful for the creation of accelerator modules, `Cython " -"`__ is also widely used for creating wrapper modules " -"for C or C++ APIs. It involves wrapping the interfaces by hand, which gives " -"a wide range of freedom in designing and optimising the wrapper code, but " -"may not be a good choice for wrapping very large APIs quickly. See the `list " -"of third-party tools `_ for " -"automatic wrapping with Cython. It also supports performance-oriented Python " -"implementations that provide a CPython-like C-API, such as PyPy and Pyston." +"``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -"アクセラレータモジュールの作成に役に立つことに加えて、 `Cython `__ は C 言語や C++ の API で書かれたものをラップするモジュールを" -"作成することにも役立ちます。インターフェイスを手動でラップする作業が必要であ" -"り、それはラッパーのソースコードを設計し最適化する上では大きな自由度を与えは" -"しますが、大規模な API を素早くラップするためにはあまり良い選択ではないかもし" -"れません。Cython を用いた自動ラッピングについては `サードパーティが提供する" -"ツールのリスト `_ を見てくださ" -"い。これらは、 PyPy や Pyston のような CPython に類似した C-API を提供する性" -"能重視の Python 実装をもサポートしています。" +"``venv`` は仮想的な Python を ``.venv`` ディレクトリの中にインストールするで" +"しょう。" -#: ../source/guides/packaging-binary-extensions.rst:171 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" -":doc:`pybind11 ` is a pure C++11 library that provides a " -"clean C++ interface to the CPython (and PyPy) C API. It does not require a " -"pre-processing step; it is written entirely in templated C++. Helpers are " -"included for Setuptools or CMake builds. It was based on `Boost.Python " -"`__, " -"but doesn't require the Boost libraries or BJam." +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." msgstr "" -":doc:`pybind11 ` は純粋な C++11 で書かれたライブラリで、綺麗" -"な C++ インタフェイスを CPython (および PyPy) の C 言語 API に提供します。事" -"前処理 (pre-processing) の段階が不要で、全体がテンプレート化された C++ で書か" -"れています。ヘルパーツールが Setuptools や CMake ビルドに含まれています。 " -"`Boost.Python `__ を基礎にしていますが、Boost ライブラリや BJam がなくてはダメと" -"いうことはありません。" +"仮想環境のディレクトリは、 ``.gitignore`` やその類似物を使ってバージョン管理" +"システムから除外しておくべきです。" -#: ../source/guides/packaging-binary-extensions.rst:178 +#: ../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:76 msgid "" -":doc:`cffi ` is a project created by some of the PyPy developers " -"to make it straightforward for developers that already know both Python and " -"C to expose their C modules to Python applications. It also makes it " -"relatively straightforward to wrap a C module based on its header files, " -"even if you don't know C yourself." +"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``." msgstr "" -":doc:`cffi ` は、 Python と C 言語の両方を知っている開発者が C 言" -"語で書いたモジュールを Python アプリケーションから単刀直入に使えるようにと何" -"人かの PyPy 開発者たちが作成しました。たとえ C 言語を知らなくても、 C 言語の" -"モジュールをそのヘッダファイルに基づいてラップすることもいくらか簡単になりま" -"した。" +"仮想環境に (依存先の) パッケージをインストールして使用できるようにするには、" +"まず *仮想環境* を ``activate`` しなければなりません。仮想環境を活性化する" +"と、その仮想環境に特有の ``python`` と ``pip`` の実行ファイルがシェルの " +"``PATH`` 変数に追加されます。" -#: ../source/guides/packaging-binary-extensions.rst:184 -msgid "" -"One of the key advantages of ``cffi`` is that it is compatible with the PyPy " -"JIT, allowing CFFI wrapper modules to participate fully in PyPy's tracing " -"JIT optimisations." +#: ../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 "" -"``cffi`` の最も重要な利点のひとつはPyPy JIT と一緒に使えることで、CFFI ラッパ" -"モジュールが PyPy の実行中の JIT 最適化に同居できるのです。" +"仮想環境が activate されたことを確認するには、 Python インタープリタの場所を" +"確かめましょう:" -#: ../source/guides/packaging-binary-extensions.rst:188 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" -"`SWIG `__ is a wrapper interface generator that allows " -"a variety of programming languages, including Python, to interface with C " -"and C++ code." +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -"`SWIG `__ は、 Python を含むさまざまなプログラミング言" -"語から C 言語や C++ のコードへのインタフェースを生成できるラッパインタフェー" -"ス生成ツールです。" +"仮想環境が active である間は、上記のコマンドは ``.venv`` ディレクトリを含む" +"ファイルパスを出力することでしょう、つまり以下のようになって終了します:" -#: ../source/guides/packaging-binary-extensions.rst:192 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" -"The standard library's ``ctypes`` module, while useful for getting access to " -"C level interfaces when header information isn't available, suffers from the " -"fact that it operates solely at the C ABI level, and thus has no automatic " -"consistency checking between the interface actually being exported by the " -"library and the one declared in the Python code. By contrast, the above " -"alternatives are all able to operate at the C *API* level, using C header " -"files to ensure consistency between the interface exported by the library " -"being wrapped and the one expected by the Python wrapper module. While " -"``cffi`` *can* operate directly at the C ABI level, it suffers from the same " -"interface inconsistency problems as ``ctypes`` when it is used that way." +"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 "" -"標準ライブラリの ``ctypes`` モジュールは、ヘッダの情報が得られない時でも C 言" -"語レベルのインタフェイスにアクセスできる点が役に立つ一方で、 C 言語の ABI の" -"レベルでのみ動作するため実際にエクスポートされているインタフェースと Python " -"コード側での宣言との間の一貫性を自動的に確認する仕組みがないという点が弊害を" -"引き起こすかもしれません。対照的に、上記の代替策はすべて C 言語の *API* のレ" -"ベルで動作するので、 C 言語のヘッダファイルを使ってライブラリからエクスポート" -"されラップされるインタフェイスと Python 側のラッパモジュールが期待しているイ" -"ンタフェースとの間の一貫性を保証することができます。 ``cffi`` は C 言語の " -"ABI のレベルで直接に動作する *ことができる* 一方で、そのように使った場合には " -"``ctypes`` と同じく一貫性を欠いたインタフェースの問題を孕みます。" +"仮想環境が active である間は、pip はパッケージをその仮想環境内にインストール" +"します。これによって、あなたの Python アプリケーションからそのパッケージをイ" +"ンポートして使用することができるようになります。" -#: ../source/guides/packaging-binary-extensions.rst:206 -msgid "Alternatives for low level system access" -msgstr "低レベルのシステムアクセスを行う代替策" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "仮想環境を非活性化 する" -#: ../source/guides/packaging-binary-extensions.rst:208 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" -"For applications that need low level system access (regardless of the " -"reason), a binary extension module often *is* the best way to go about it. " -"This is particularly true for low level access to the CPython runtime " -"itself, since some operations (like releasing the Global Interpreter Lock) " -"are simply invalid when the interpreter is running code, even if a module " -"like ``ctypes`` or ``cffi`` is used to obtain access to the relevant C API " -"interfaces." +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" msgstr "" -"(理由を問わず) 低レベルのシステムにアクセスする必要のあるアプリケーションに" -"とって、バイナリ拡張モジュールはしばしば *進むべき最良の道* です。これは、 " -"``ctypes`` や ``cffi`` といったモジュールが適切な C 言語の API インタフェース" -"へのアクセスを取得するために使われている場合であってさえも、 (グローバルイン" -"タプリタロックの解除のような) いくつかの操作がインタプリタがコードを実行して" -"いる時には無効であるということだけを見ても、CPython ランタイム自身の低レベル" -"部分にアクセスする際によく当てはまると言えます。" +"プロジェクトを切り替えたい、あるいは、仮想環境から離脱したい時は、仮想環境を " +"``deactivate`` してください:" -#: ../source/guides/packaging-binary-extensions.rst:216 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" -"For cases where the extension module is manipulating the underlying " -"operating system or hardware (rather than the CPython runtime), it may " -"sometimes be better to just write an ordinary C library (or a library in " -"another systems programming language like C++ or Rust that can export a C " -"compatible ABI), and then use one of the wrapping techniques described above " -"to make the interface available as an importable Python module." +"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 "" -"拡張モジュールが (CPythonのランタイムではなく) 下層のオペレーティングシステム" -"やハードウェアを操作しようとする場合には、単純に通常の C 言語 (または C++ や " -"Rust のような別のシステム言語で C 言語と互換性のある ABI をエクスポートできる" -"もの) でライブラリを書いて、それを上述のようなインポート可能な Python のモ" -"ジュールとしてインタフェースを構築できるラッピングテクニックを使う方が良いと" -"いう場合もあるでしょう。" +"シェルを終了すれば、仮想環境を非活性化 することになるでしょう。" +"もし、新しいシェル窓を開いて、そこで仮想環境を使いたい時は、再活性化 " +" してください。" -#: ../source/guides/packaging-binary-extensions.rst:225 -msgid "Implementing binary extensions" -msgstr "バイナリ拡張を実装する" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "仮想環境を再活性化 する" -#: ../source/guides/packaging-binary-extensions.rst:227 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" -"The CPython :doc:`Extending and Embedding ` guide " -"includes an introduction to writing a :doc:`custom extension module in C " -"`." +"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 "" -"CPython の :doc:`拡張と埋め込み ` のガイドには、 :" -"doc:`C 言語による独自の拡張モジュール ` を書くた" -"めの導入的な説明があります。" +"既存の仮想環境を活性化 したい場合は、仮想環境の活性化に関する上述" +"のやり方に従ってください。新しい仮想環境を作成する必要はありません。" -#: ../source/guides/packaging-binary-extensions.rst:231 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" -"FIXME: Elaborate that all this is one of the reasons why you probably " -"*don't* want to handcode your extension modules :)" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." msgstr "" -"FIXME: これが拡張モジュールを支援ツールなしで書きたいと *思わない* であろうと" -"いう理由のひとつであることを詳しく説明すること :)" - -#: ../source/guides/packaging-binary-extensions.rst:236 -msgid "Extension module lifecycle" -msgstr "拡張モジュールのライフサイクル" +":ref:`pip` は Python の参照モデルとなるパッケージマネージャです。仮想環境内で" +"パッケージのインストールや更新に用いられます。" -#: ../source/guides/packaging-binary-extensions.rst:238 -#: ../source/guides/packaging-binary-extensions.rst:244 -#: ../source/guides/packaging-binary-extensions.rst:250 -#: ../source/guides/packaging-binary-extensions.rst:256 -#: ../source/guides/packaging-binary-extensions.rst:376 -msgid "FIXME: This section needs to be fleshed out." -msgstr "FIXME: この節には肉付けが必要です。" +#: ../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 "" +"MacOS 用の Python インストーラは pip を含んでいます。Linux では、 ``python3-" +"pip`` のような追加のパッケージをインストールしなければならないかもしれませ" +"ん。以下のようにすると pip が最新版であることを確実にすることができます:" -#: ../source/guides/packaging-binary-extensions.rst:242 -msgid "Implications of shared static state and subinterpreters" -msgstr "shared static state やサブインタプリタの影響" +#: ../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/packaging-binary-extensions.rst:248 -msgid "Implications of the GIL" -msgstr "GIL の影響" +#: ../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/packaging-binary-extensions.rst:254 -msgid "Memory allocation APIs" -msgstr "メモリを割り当てる API 群" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "その後、pip が最新版になっているはずです:" -#: ../source/guides/packaging-binary-extensions.rst:262 -msgid "ABI Compatibility" -msgstr "ABI の互換性" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "pip を使ってパッケージをインストールする" -#: ../source/guides/packaging-binary-extensions.rst:264 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" -"The CPython C API does not guarantee ABI stability between minor releases " -"(3.2, 3.3, 3.4, etc.). This means that, typically, if you build an extension " -"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." +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." msgstr "" -"CPython の C 言語 API は、マイナーリリース (3.2, 3.3, 3.4 等) 間の ABI の互換" -"性を保証しません。これが意味するところは、典型的には、Python のあるバージョン" -"向けに拡張モジュールをビルドした時にマイナーバージョンまで同じ Python での動" -"作が保証されるだけであって、他のマイナーバージョンについては保証されないとい" -"うことです。" +"仮想環境が活性化状態にある時には、パッケージ群をインストールすることができま" +"す。パッケージをインストールするには ``pip install`` コマンドを使ってくださ" +"い。" -#: ../source/guides/packaging-binary-extensions.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "パッケージをインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" -"Python 3.2 introduced the Limited API, with is a well-defined subset of " -"Python's C API. The symbols needed for the Limited API form the \"Stable " -"ABI\" which is guaranteed to be compatible across all Python 3.x versions. " -"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." +"For example,let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" msgstr "" -"Python 3.2 では、Python の C 言語 API のよく定義されたサブセットとして " -"Limited API を導入しました。Limited API が必要とするシンボル群は、Python 3.x " -"のすべてのバージョンを通じて互換性を保つことが保証された \"Stable ABI\" を形" -"成しています。Stable ABI を使ってビルドされた拡張部分を含む Wheel は、Python " -"3.x のすべてのバージョンで互換性を保っていることを反映するために ``abi3`` と" -"いう ABI タグを使用します。" +"例として、 :term:`Python Package Index (PyPI)` から `Requests`_ ライブラリを" +"インストールしてみましょう:" -#: ../source/guides/packaging-binary-extensions.rst:277 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" -"CPython's :doc:`C API stability` page provides detailed " -"information about the API / ABI stability guarantees, how to use the Limited " -"API and the exact contents of the \"Limited API\"." +"pip should download requests and all of its dependencies and install them:" msgstr "" -"CPython の :doc:`C 言語 API の安定性 ` のページには、 " -"API/ABI の安定性保証、つまり、 Limited API をどのように使うのかや \"Limited " -"API\" の正確な内容について詳しい情報があります。" - -#: ../source/guides/packaging-binary-extensions.rst:283 -msgid "Building binary extensions" -msgstr "バイナリ拡張をビルドする" - -#: ../source/guides/packaging-binary-extensions.rst:285 -msgid "FIXME: Cover the build-backends available for building extensions." -msgstr "FIXME: Cover the build-backends available for building extensions." +"pip が requests とその依存先パッケージをすべてダウンロードしてインストールす" +"るはずです:" -#: ../source/guides/packaging-binary-extensions.rst:288 -msgid "Building extensions for multiple platforms" -msgstr "複数のプラットフォーム向けに拡張モジュールをビルドする" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "特定のバージョンのパッケージをインストールする" -#: ../source/guides/packaging-binary-extensions.rst:290 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" -"If you plan to distribute your extension, you should provide :term:`wheels " -"` for all the platforms you intend to 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`." +"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 "" -"あなたが自分の書いた拡張モジュールを配布するつもりがあるなら、あたながサポー" -"トしようと思うすべてのプラットフォーム向けに :term:`wheels ` を準備す" -"るべきです。通常はこれらを継続的インテグレーション (CI) システム上でビルドし" -"ます。:ref:`cibuildwheel` や :ref:`multibuild` のような CI から再配布が非常に" -"やりやすいバイナリをビルドするのを補助するツールの存在が知られています。" +":term:`バージョン指定子 ` を使えば、 pip でパッケージのバー" +"ジョンを指定してインストールすることができます。例えば、 ``requests`` の特定" +"のバージョンをインストールするなら:" + +#: ../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/packaging-binary-extensions.rst:296 -msgid "" -"For most extensions, you will need to build wheels for all the platforms you " -"intend to support. This means that the number of wheels you need to build is " -"the product of::" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -"ほとんどの拡張部分向けに、すべてのサポートするつもりのあるプラットフォーム用" -"の wheel をビルドする必要があるでしょう。これが意味するところは、ビルドする必" -"要のある wheel 群の数が次のような掛け算になるだろうということです::" +"``--pre`` フラグを使ってパッケージのリリース前のバージョンをインストールする" +"には:" -#: ../source/guides/packaging-binary-extensions.rst:302 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "(パッケージの) extra 部分をインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" -"Using CPython's :ref:`Stable ABI ` can help " -"significantly reduce the number of wheels you need to provide, since a " -"single wheel on a platform can be used with all Python minor versions; " -"eliminating one dimension of the matrix. It also removes the need to " -"generate new wheels for each new minor version of Python." +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" msgstr "" -"CPython の :ref:`Stable ABI ` を使うことで、準備する必要" -"のある wheel の数を大いに減らすことに役立つでしょう、というのは、あるプラット" -"フォーム上の単一の wheel が Python のすべてのマイナーバージョンで使える; つま" -"り、マトリクスの次元をひとつ削除することになるからです。さらに、新しいマイ" -"ナーバージョンの Python が出現するたびに新たに wheel を生成する必要もなくなり" -"ます。" +"必須ではない `extra`_ 部分を持つものがパッケージの中にはあります。extra の名" +"前を角括弧([, ])の中に書くことで pip にインストールするように指示することがで" +"きます。" -#: ../source/guides/packaging-binary-extensions.rst:309 -msgid "Binary extensions for Windows" -msgstr "Windows 向けのバイナリ拡張" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "ソースコードからパッケージをインストールする" -#: ../source/guides/packaging-binary-extensions.rst:311 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" -"Before it is possible to build a binary extension, it is necessary to ensure " -"that you have a suitable compiler available. On Windows, Visual C is used to " -"build the official CPython interpreter, and should be used to build " -"compatible binary extensions. To set up a build environment for binary " -"extensions, install `Visual Studio Community Edition `__ - any recent version is fine." +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" msgstr "" -"バイナリ拡張をビルドできるようになる前に、適切なコンパイラが利用できるように" -"なっていることを保証しなければなりません。Windows 上でCPython インタプリタを" -"ビルドするのに Visual C が使われていますが、互換性のあるバイナリ拡張をビルド" -"する時にも同じコンパイラを使うべきです。バイナリ拡張のためのビルド環境を構築" -"するためには、 `Visual Studio コミュニティエディション `__ をインストールしてください - 最近のバージョンな" -"らどれでも構いません。" +"pip は、ソースコードから直接にパッケージをインストールすることができます。例" +"えば、 ``google-auth`` ディレクトリの中にあるソースコードをインストールするに" +"は:" -#: ../source/guides/packaging-binary-extensions.rst:318 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" -"One caveat: if you use Visual Studio 2019 or later, your extension will " -"depend on an \"extra\" file, ``VCRUNTIME140_1.dll``, in addition to the " -"``VCRUNTIME140.dll`` that all previous versions back to 2015 depend on. This " -"will add an extra requirement to using your extension on versions of CPython " -"that do not include this extra file. To avoid this, you can add the compile-" -"time argument ``/d2FH4-``. Recent versions of Python may include this file." +"Additionally, pip can install packages from source in :doc:`development mode " +"`, meaning that changes to the source " +"directory will immediately affect the installed package without needing to " +"re-install:" msgstr "" -"注意: Visual Studio 2019 またはこれ以降のバージョンを使う場合には、あなたの拡" -"張モジュールは、2015 までのそれ以前のバージョンで依存していた ``VCRUNTIME140." -"dll`` に加えて、\"追加的な\" ファイルである ``VCRUNTIME140_1.dll`` にも依存す" -"るでしょう。この追加のファイルを同梱していないバージョンの CPython 上であなた" -"の拡張モジュールを使う場合には、要求事項が追加されることになります。コンパイ" -"ル時に引数 ``/d2FH4`` を追加しておくことで、これを避けることができます。最近" -"のバージョンの Python ならこのファイルを同梱しているかもしれません。" +"さらに、 pip は :doc:`開発モード ` で" +"ソースコードからパッケージをインストールすることができます。つまり、ソース" +"コードを修正すると、再インストールしなくても、すぐにインストール済みのパッ" +"ケージに反映されます。" -#: ../source/guides/packaging-binary-extensions.rst:326 +#: ../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:349 msgid "" -"Building for Python prior to 3.5 is discouraged, because older versions of " -"Visual Studio are no longer available from Microsoft. If you do need to " -"build for older versions, you can set ``DISTUTILS_USE_SDK=1`` and " -"``MSSdk=1`` to force a the currently activated version of MSVC to be found, " -"and you should exercise care when designing your extension not to malloc/" -"free memory across different libraries, avoid relying on changed data " -"structures, and so on. Tools for generating extension modules usually avoid " -"these things for you." +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" msgstr "" -"Visual Studio の古いバージョンがもはや Microsoft 社から入手できないので、3.5" -"より古いバージョンの Python 向けにビルドすることは推奨されません。どうしても" -"古いバージョン向けにビルドする必要がある場合には、 ``DISTUTILS_USE_SDK=1`` お" -"よび ``MSSdk=1`` をセットすることで現在も使用可能なバージョンの MSVC が見つか" -"るようにすることと、あなたの拡張モジュールの中でライブラリを跨いでメモリを " -"malloc/free することのないように設計を見直すこと、また、修正されたデータ構造" -"に依存しないようにすることなどが必要です。拡張モジュールを生成するツール群" -"は、通常はこのようなことが起こらないようにしてくれています。" - -#: ../source/guides/packaging-binary-extensions.rst:337 -msgid "Binary extensions for Linux" -msgstr "Linux 向けのバイナリ拡張" +"pip は、バージョン管理システムから直接に、パッケージをインストールすることが" +"できます。例えば、git リポジトリから直接にインストールするには:" -#: ../source/guides/packaging-binary-extensions.rst:339 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" -"Linux binaries must use a sufficiently old glibc to be compatible with older " -"distributions. The `manylinux `_ Docker " -"images provide a build environment with a glibc old enough to support most " -"current Linux distributions on common architectures." +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." msgstr "" -"Linux のバイナリは、古い配布物と互換性を保つために十分に古い glibc を使わなけ" -"ればなりません。 `manylinux `_ の Docker " -"イメージを使えば、よくあるアーキテクチャのほとんどの現行版 Linux 配布物をサ" -"ポートするのに十分なほど古い glibc を伴ったビルド環境を準備できるでしょう。" +"サポートされているバージョン管理システムや文法について、詳しくは :ref:`VCS サ" +"ポート ` の pip の説明文書を見てください。" -#: ../source/guides/packaging-binary-extensions.rst:345 -msgid "Binary extensions for macOS" -msgstr "macOS 向けのバイナリ拡張" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "ローカルアーカイブからインストールする" -#: ../source/guides/packaging-binary-extensions.rst:347 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" -"Binary compatibility on macOS is determined by the target minimum deployment " -"system, e.g. *10.9*, which is often specified with the " -"``MACOSX_DEPLOYMENT_TARGET`` environmental variable when building binaries " -"on macOS. When building with setuptools / distutils, the deployment target " -"is specified with the flag ``--plat-name``, e.g. ``macosx-10.9-x86_64``. For " -"common deployment targets for macOS Python distributions, see the `MacPython " -"Spinning Wheels wiki `_." +"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 "" -"macOS におけるバイナリ互換性は、 macOS のバイナリをビルドする際にしばしば " -"``MACOSX_DEPLOYMENT_TARGET`` 環境変数で指定される例えば *10.9* のようなター" -"ゲットの最小デプロイメントシステムで決まります。 setuptools や distutils でビ" -"ルドする時には、デプロイメントターゲットは ``--plat-name`` フラグを使って、例" -"えば ``macosx-10.9-x86_64`` のように指定されます。 macOS 上の Python 配布物向" -"けのよくあるデプロイメントターゲットについては、 `MacPython スピンニングホ" -"イール wiki `_ を見て" -"ください。" - -#: ../source/guides/packaging-binary-extensions.rst:357 -msgid "Publishing binary extensions" -msgstr "バイナリ拡張を公開する" +"もし :term:`配布パッケージ ` のアーカイブ ( zip や " +"wheel や tar ファイル) をローカルに持っているなら、 pip でそこから直接にイン" +"ストールすることができます:" -#: ../source/guides/packaging-binary-extensions.rst:359 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" -"Publishing binary extensions through PyPI uses the same upload mechanisms as " -"publishing pure Python packages. You build a wheel file for your extension " -"using the build-backend and upload it to PyPI using :doc:`twine `." +"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 "" -"PyPI を通じてバイナリ拡張を公開する時にも、純 Python のパッケージを公開すると" -"きと同じアップロードのメカニズムを使います。その拡張の wheel をビルドバックエ" -"ンドを使ってビルドし、 :doc:`twine ` を使って PyPI にアップロー" -"ドするということです。" - -#: ../source/guides/packaging-binary-extensions.rst:365 -msgid "Avoid binary-only releases" -msgstr "バイナリだけのリリースを避ける" +"複数のパッケージのアーカイブを置いたディレクトリを pip に探索させるようにし" +"て、:term:`Python パッケージインデックス ` を全" +"く利用しないということも可能です:" -#: ../source/guides/packaging-binary-extensions.rst:367 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" -"It is strongly recommended that you publish your binary extensions as well " -"as the source code that was used to build them. This allows users to build " -"the extension from source if they need to. Notably, this is required for " -"certain Linux distributions that build from source within their own build " -"systems for the distro package repositories." +"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 "" -"バイナリ拡張を公開する時にはそれをビルドする際に用いたソースコードも公開する" -"ことが強く推奨されています。こうすることで、必要であればユーザがその拡張を" -"ソースコードからビルドすることができます。特筆すべきことに、 Linux ディストリ" -"ビューションの中には、そのディストロ向けのパッケージリポジトリの独自のビルド" -"システム内でソースコードからビルドすることを要求するものがあるのです。" - -#: ../source/guides/packaging-binary-extensions.rst:374 -msgid "Weak linking" -msgstr "弱いリンキング " +"この機能は、限定的なインターネット接続しか得られないシステムでパッケージをイ" +"ンストールする際や、配布物パッケージの出自を厳密に管理したい時には便利です。" -#: ../source/guides/packaging-binary-extensions.rst:379 -msgid "Additional resources" -msgstr "追加のリソース" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "他のインデックスサイトからインストールする" -#: ../source/guides/packaging-binary-extensions.rst:381 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" -"Cross-platform development and distribution of extension modules is a " -"complex topic, so this guide focuses primarily on providing pointers to " -"various tools that automate dealing with the underlying technical " -"challenges. The additional resources in this section are instead intended " -"for developers looking to understand more about the underlying binary " -"interfaces that those systems rely on at runtime." +"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/packaging-binary-extensions.rst:388 -msgid "Cross-platform wheel generation with scikit-build" -msgstr "sckit-build を用いたクロスプラットフォームな wheel の生成" +":term:`Python パッケージインデックス ` 以外のと" +"ころからパッケージをダウンロードしたいのであれば、 ``--index-url`` オプション" +"でできます:" -#: ../source/guides/packaging-binary-extensions.rst:390 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" -"The `scikit-build `_ package " -"helps abstract cross-platform build operations and provides additional " -"capabilities when creating binary extension packages. Additional " -"documentation is also available on the `C runtime, compiler, and build " -"system generator `_ for Python binary extension modules." +"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 "" -"`scikit-build `_ は、抽象的な" -"ビルド作業を補助し、バイナリ拡張のパッケージを作成する時に必要な追加的な能力" -"を提供します。 Python のバイナリ拡張モジュールに関するさらなる説明文書は、 " -"`C 言語におけるランタイム・コンパイラ・ビルドシステム生成器 `_ にあります。" +":term:`Python パッケージインデックス ` と別のイ" +"ンデックスを同時に使いたいのであれば、 ``--extra-index-url`` オプションででき" +"ます:" -#: ../source/guides/packaging-binary-extensions.rst:398 -msgid "Introduction to C/C++ extension modules" -msgstr "C/C++ による拡張モジュールの紹介" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "パッケージを更新する" -#: ../source/guides/packaging-binary-extensions.rst:400 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" -"For a more in depth explanation of how extension modules are used by CPython " -"on a Debian system, see the following articles:" +"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 "" -"Debian システム上で CPython がどのようにして拡張モジュールを使うのかについ" -"て、もっと深掘りした説明が次の記事に出ています:" +"pip に ``--upgrade`` オプションを与えるとパッケージの入れ替え更新ができます。" +"例えば、 ``requests`` とその依存先パッケージの最新版をインストールしたいのな" +"ら:" -#: ../source/guides/packaging-binary-extensions.rst:403 +#: ../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:454 msgid "" -"`What are (c)python extension modules? `_" +"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 "" -"`(c)python の拡張モジュールとはどんなものか？ `_" +"パッケージをひとつひとつインストールする代わりに、pip では :ref:" +"`Requirements ファイル ` にすべての依存先パッケージを" +"列挙しておくことができます。例えば、 :file:`requirements.txt` を下記を含むよ" +"うに作成しておいて:" -#: ../source/guides/packaging-binary-extensions.rst:404 -msgid "`Releasing the gil `_" +#: ../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 "" -"`gil をリリースする `_" +"このファイルに書いてあるパッケージを全てインストールするようにと、 ``-r`` オ" +"プションを与えることで pip に指示します:" -#: ../source/guides/packaging-binary-extensions.rst:405 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +msgstr "依存関係を凍結する" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" -"`Writing cpython extension modules using C++ `_" +"Pip can export a list of all installed packages and their versions using the " +"``freeze`` command:" msgstr "" -"`C++ で cpython の拡張モジュールを書く `_" +"Pip では、 ``freeze`` コマンドを使うことで、インストール済みの全パッケージの" +"バージョン付きのリストを取り出すことができます:" -#: ../source/guides/packaging-namespace-packages.rst:5 -msgid "Packaging namespace packages" -msgstr "名前空間パッケージをパッケージする" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 +msgid "Which will output a list of package specifiers such as:" +msgstr "それは、次に挙げるようなパッケージ指定子のリストを出力します:" -#: ../source/guides/packaging-namespace-packages.rst:7 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" -"Namespace packages allow you to split the sub-packages and modules within a " -"single :term:`package ` across multiple, separate :term:" -"`distribution packages ` (referred to as " -"**distributions** in this document to avoid ambiguity). For example, if you " -"have the following package structure:" +"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 "" -"名前空間 (Namespace) パッケージは、複数かつ個別の :term:`パッケージ ` (曖昧にならないようにこの文書では **配布物** と呼ぶことにする) を越" -"えて、単一の :term:`パッケージ ` の中のサブパッケージやモ" -"ジュールを分離できるようにすることができます。例えば、下に示すようなパッケー" -"ジ構造であれば:" +"``pip freeze`` コマンドは、環境内にインストール済みのすべてのパッケージの正確" +"なバージョンを再生成することができる :ref:`pip:Requirements Files` を作成する" +"のに便利に使えます。" -#: ../source/guides/packaging-namespace-packages.rst:26 -msgid "And you use this package in your code like so::" -msgstr "そして、このパッケージを自分のソースコード中で使うにはこのようにする::" +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "virtualenv を使ってパッケージをインストールする" -#: ../source/guides/packaging-namespace-packages.rst:31 -msgid "Then you can break these sub-packages into two separate distributions:" +#: ../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 "" -"そうすることで、これらのサブパッケージ群を別々のふたつの配布物に分割すること" -"ができます:" +"このガイド文書では、:ref:`pip` と隔離された Python 環境を作成するツールである" +"ところの :ref:`virtualenv` を使ってパッケージをインストールする方法について議" +"論します。" -#: ../source/guides/packaging-namespace-packages.rst:50 -msgid "Each sub-package can now be separately installed, used, and versioned." +#: ../source/guides/installing-using-virtualenv.rst:8 +msgid "" +"This \"how to\" guide on installing packages and using :ref:`virtualenv` is " +"under development. Please refer to the :ref:`virtualenv` documentation for " +"details on installation and usage." msgstr "" -"それぞれのサブパッケージは、今や、個別にインストール・使用・バージョン管理す" -"ることができます。" +"パッケージをインストールすることと :ref:`virtualenv` を使うことに関するこの " +"\"how to\" ガイドは、作成途中です。:ref:`virtualenv` の説明文書にインストール" +"方法や使い方について詳しく出ていますので、そちらもご覧ください。" -#: ../source/guides/packaging-namespace-packages.rst:52 +#: ../source/guides/installing-using-virtualenv.rst:13 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 " -"from a single company). However, namespace packages come with several " -"caveats and are not appropriate in all cases. A simple alternative is to use " -"a prefix on all of your distributions such as ``import " -"mynamespace_subpackage_a`` (you could even use ``import " -"mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." +"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." msgstr "" -"名前空間パッケージは、 (単独の会社から出ている複数の製品向けのクライアントラ" -"イブラリの巨大な集積のような) 緩やかに関連したパッケージが多数含まれるコレク" -"ションに役立つでしょう。しかしながら、名前空間パッケージにはいくつかの注意書" -"きがあって、全ての場合に適切と言うわけではありません。単純明快な代替策は、あ" -"なたの配布物のすべてについて ``import mynamespace_subpackage_a`` のような接頭" -"語を使うことです (インポートするオブジェクトの名前を短く保つために ``import " -"mynamespace_subpackage_a as subpackage_a`` のようにインポートすることさえでき" -"ます) 。" +"この文書では **パッケージ** という用語を :term:`配布パッケージ ` の意味で使いますが、これは Python ソースコードでモジュールをイン" +"ポートするという意味で使われる :term:`パッケージインポート ` " +"とは異なります。" -#: ../source/guides/packaging-namespace-packages.rst:62 -msgid "Creating a namespace package" -msgstr "名前空間パッケージを作成する" +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "PyPI によく合う README を作る" -#: ../source/guides/packaging-namespace-packages.rst:64 +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 msgid "" -"There are currently two different approaches to creating namespace packages, " -"from which the latter is discouraged:" +"README files can help your users understand your project and can be used to " +"set your project's description on PyPI. This guide helps you create a README " +"in a PyPI-friendly format and include your README in your package so it " +"appears on PyPI." msgstr "" -"現在、名前空間パッケージを作るには２個の異なる手法がありますが、後者は使わな" -"い方が良いとされています:" +"README ファイルは、あなたのパッケージのユーザがプロジェクトを理解するのを助" +"け、プロジェクトの説明をするのに使われています。このガイドでは、PyPI によく合" +"う形で README を作成するのを助け、あなたのパッケージの README が PyPI で表示" +"されるようにします。" -#: ../source/guides/packaging-namespace-packages.rst:67 +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "README ファイルを作成する" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 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 " -"if packages in your namespace only ever need to support Python 3 and " -"installation via ``pip``." +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." msgstr "" -"`組み込みの名前空間パッケージ`_ を用いる方法。この種の名前空間パッケージは :" -"pep:`420` で定義されていて、 Python 3.3 およびそれ以降で利用することができま" -"す。パッケージ中の名前空間が Python 3 だけをサポートすればよくて ``pip`` でイ" -"ンストールするのであれば、これが推奨される方法です。" +"Python プロジェクトにおける READMEファイルは、しばしば ``README`` ・ " +"``README.txt`` ・ ``README.rst`` ・ ``README.md`` などと命名されます。" -#: ../source/guides/packaging-namespace-packages.rst:71 +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 msgid "" -"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " -"packages`_ and `pkg_resources-style namespace packages`_." +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" msgstr "" -"`レガシー名前空間パッケージ群`_ を使ってください。これは`pkgutil 型の名前空間" -"パッケージ`_ および `pkg_resources 型の名前空間パッケージ`_ から構成されてい" -"ます。" +"あなたの README を PyPI で正しく表示するためには、PyPI がサポートするマーク" +"アップ言語を選択する必要があります。 `PyPI の README レンダラ `_ としてサポートされているのは:" -#: ../source/guides/packaging-namespace-packages.rst:75 -msgid "Native namespace packages" -msgstr "組み込みの名前空間パッケージ" +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "プレーンテキスト" -#: ../source/guides/packaging-namespace-packages.rst:77 +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 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 (following :ref:`src-layout `):" +"`reStructuredText `_ (without " +"Sphinx extensions)" msgstr "" -"Python 3.3 では :pep:`420` から **暗黙の** 名前空間パッケージを追加しました。" -"ネイティブな名前空間パッケージを作成するのに必要なことは、名前空間パッケージ" -"のディレクトリから :file:`__init__.py` を取り除くことだけです。ファイル構造の" -"例はこちら (:ref:`ソースコードレイアウト ` に従いま" -"す):" +"`reStructuredText `_ (Sphinx 拡張な" +"し)" -#: ../source/guides/packaging-namespace-packages.rst:94 +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 msgid "" -"It is extremely important that every distribution that uses the namespace " -"package omits the :file:`__init__.py` or uses a pkgutil-style :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." +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" msgstr "" -"名前空間パッケージを用いる各配布物で :file:`__init__.py` を省くこと、また" -"は、 pkgutil 型の :file:`__init__.py` を使用することが極めて重要です。もしい" -"ずれかの配布物でこれを忘れると、名前空間の論理が破綻して、他のサブパッケージ" -"をインポートすることができなくなります。" +"マークダウン (デフォルトでは `GitHub Flavored Markdown `_ 、あるいは `CommonMark `_)" -#: ../source/guides/packaging-namespace-packages.rst:99 +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 msgid "" -"The ``src-layout`` directory structure allows automatic discovery of " -"packages by most :term:`build backends `. See :ref:`src-" -"layout-vs-flat-layout` for more information. If however you want to manage " -"exclusions or inclusions of packages yourself, this is possible to be " -"configured in the top-level :file:`pyproject.toml`:" +"It's customary to save your README file in the root of your project, in the " +"same directory as your :file:`setup.py` file." msgstr "" -"``src-layout`` ディレクトリ構造によって、ほとんどの :term:`ビルドバックエン" -"ド ` が自動的にパッケージ群を発見できるようになります。もっと" -"情報が欲しい場合は :ref:`src-layout-vs-flat-layout` を見てください。しかしな" -"がら、パッケージの包含・除外を自分自身で管理したいのであれば、トップレベル" -"の :file:`pyproject.toml` を設定することで可能です:" +"README ファイルについては、 :file:`setup.py` ファイルと同様にプロジェクトの" +"ルートディレクトリに置くのが慣習になっています。" -#: ../source/guides/packaging-namespace-packages.rst:117 -msgid "The same can be accomplished with a :file:`setup.cfg`:" -msgstr "同じことが :file:`setup.cfg` で達成できます:" +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "README にパッケージのメタデータを含ませる" -#: ../source/guides/packaging-namespace-packages.rst:129 -msgid "Or :file:`setup.py`:" -msgstr "または :file:`setup.py` ファイル:" +#: ../source/guides/making-a-pypi-friendly-readme.rst:27 +msgid "" +"To include your README's contents as your package description, set your " +"project's ``Description`` and ``Description-Content-Type`` metadata, " +"typically in your project's :file:`setup.py` file." +msgstr "" +"README の内容をパッケージの説明として引用させるには、典型的にはプロジェクト" +"の :file:`setup.py` ファイルに、プロジェクトの ``Description`` と " +"``Description-Content-Type`` のふたつのメタデータを設定しておきましょう。" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr ":ref:`description-optional`" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr ":ref:`description-content-type-optional`" -#: ../source/guides/packaging-namespace-packages.rst:142 +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 msgid "" -":ref:`setuptools` will search the directory structure for implicit namespace " -"packages by default." +"For example, to set these values in a package's :file:`setup.py` file, use " +"``setup()``'s ``long_description`` and ``long_description_content_type``." msgstr "" -":ref:`setuptools` は、デフォルトでは暗黙の名前空間パッケージを探してディレク" -"トリ構造を探索します。" +"例えば、これらの値をパッケージの :file:`setup.py` ファイルに設定するために" +"は、 ``setup()`` の ``long_description`` と " +"``long_description_content_type`` を使ってください。" -#: ../source/guides/packaging-namespace-packages.rst:145 +#: ../source/guides/making-a-pypi-friendly-readme.rst:39 msgid "" -"A complete working example of two native namespace packages can be found in " -"the `native namespace package example project`_." +"Set the value of ``long_description`` to the contents (not the path) of the " +"README file itself. Set the ``long_description_content_type`` to an accepted " +"``Content-Type``-style value for your README file's markup, such as ``text/" +"plain``, ``text/x-rst`` (for reStructuredText), or ``text/markdown``." msgstr "" -"ふたつの名前空間パッケージの完全な動作例は、 `組み込みの名前空間パッケージの" -"使用例プロジェクト`_ にあります。" +"``long_desctription`` には README ファイルの内容それ自体 (パスではなく) を設" +"定してください。 ``long_description_content_type`` には、README ファイルの" +"マークアップの型を受け入れ可能な ``Content-Type`` 風の書き方、すなわち " +"``text/plain`` ・ ``text/x-rst`` (reStructuredText の場合) ・ ``text/" +"markdown`` から選んで設定してください。" -#: ../source/guides/packaging-namespace-packages.rst:151 +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 msgid "" -"Because native and pkgutil-style namespace packages are largely compatible, " -"you can use native namespace packages in the distributions that only support " -"Python 3 and pkgutil-style namespace packages in the distributions that need " -"to support Python 2 and 3." +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" msgstr "" -"組み込み名前空間パッケージと pkgutil 型の名前空間パッケージは、多くの部分で互" -"換性があるので、 Python 3 しかサポートしない配布物では組み込み名前空間パッ" -"ケージを使用し、 Python 2 と Python 3 の両方をサポートしなければならない配布" -"物では pkgutil型名前空間パッケージを使うことが可能です。" +"プロジェクトの説明を GitHub 方言のマークダウンで書くのであれば、以下のツール" +"を更新しておくことを忘れないでください:" -#: ../source/guides/packaging-namespace-packages.rst:158 -msgid "Legacy namespace packages" -msgstr "伝統的な名前空間パッケージ群" +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "各ツールは少なくとも次のバージョンでなければなりません:" -#: ../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." +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" msgstr "" -"これらのふたつの方法は、 :pep:`420` 以前に名前空間を作成するのに使われました" -"が、今では過去のやり方であると考えられていて、すでにこの方法を使っているパッ" -"ケージとの互換性を必要とする場合を除いては使われるべきではないと考えられてい" -"ます。また、 :doc:`pkg_resources ` は非推奨になりま" -"した。" -#: ../source/guides/packaging-namespace-packages.rst:165 -msgid "" -"To migrate an existing package, all packages sharing the namespace must be " -"migrated simultaneously." +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" msgstr "" -"既存のパッケージを移植するためには、名前空間を共有するすべてのパッケージが同" -"時に移植されなければなりません。" -#: ../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 " -"compatible with the other methods. It's inadvisable to use different methods " -"in different distributions that provide packages to the same namespace." +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" msgstr "" -"組み込みの名前空間パッケージや pkgutil 型の名前空間パッケージは多くの点で互換" -"性がありますが、 pkg_resources 型の名前空間パッケージは他の手法とは互換性があ" -"りません。同じ名前空間向けにパッケージを提供するような複数の配布物で、異なる" -"手法を用いることは推奨されません。" - -#: ../source/guides/packaging-namespace-packages.rst:174 -msgid "pkgutil-style namespace packages" -msgstr "pkgutil 型名前空間パッケージ" -#: ../source/guides/packaging-namespace-packages.rst:176 +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 msgid "" -"Python 2.3 introduced the :doc:`pkgutil ` module and " -"the :py:func:`python:pkgutil.extend_path` function. This can be used to " -"declare namespace packages that need to be compatible with both Python 2.3+ " -"and Python 3. This is the recommended approach for the highest level of " -"compatibility." +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" msgstr "" -"Python 2.3 で :doc:`pkgutil ` モジュールと :py:func:" -"`python:pkgutil.extend_path` 関数が導入されました。Python 2.3+ と Python 3 の" -"両方に互換性を持つ必要がある名前空間パッケージを宣言するのにこれが使えるかも" -"しれません。これは、互換性のレベルが最も高くなるアプローチとして推奨されてい" -"ます。" +"プロジェクトの配布物パッケージをアップロードする時は ``twine`` を使うことを推" +"奨します。" -#: ../source/guides/packaging-namespace-packages.rst:181 +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 msgid "" -"To create a pkgutil-style namespace package, you need to provide an :file:" -"`__init__.py` file for the namespace package:" +"For example, see this :file:`setup.py` file, which reads the contents of :" +"file:`README.md` as ``long_description`` and identifies the markup as GitHub-" +"flavored Markdown:" msgstr "" -"pkgutil 型の名前空間パッケージを作成するには、その名前空間パッケージ用に :" -"file:`__init__.py` ファイルを準備する必要があります:" +"例えば、この :file:`setup.py` ファイルでは、 :file:`README.md` の内容を読み" +"取って ``long_description`` としていて、マークアップ方式は GitHub 方言のマー" +"クダウンを指定しています:" -#: ../source/guides/packaging-namespace-packages.rst:195 -#: ../source/guides/packaging-namespace-packages.rst:242 +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "reStructuredText マークアップを検証する" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 msgid "" -"The :file:`__init__.py` file for the namespace package needs to contain the " -"following:" +"If your README is written in reStructuredText, any invalid markup will " +"prevent it from rendering, causing PyPI to instead just show the README's " +"raw source." msgstr "" -"名前空間パッケージ用の :file:`__init__.py` ファイルは、次に示すものを含んでい" -"る必要があります:" +"README を reStructuredText で書いている場合、無効なマークアップがひとつでもあ" +"ると描画できないので、PyPI 上では README の生のソースコードを表示するだけに" +"なってしまいます。" -#: ../source/guides/packaging-namespace-packages.rst:202 -#: ../source/guides/packaging-namespace-packages.rst:249 +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 msgid "" -"**Every** distribution that uses the namespace package must include such an :" -"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." +"Note that Sphinx extensions used in docstrings, such as :doc:`directives " +"` and :doc:`roles ` (e.g., \"``:py:func:`getattr```\" or \"``:ref:`my-" +"reference-label```\"), are not allowed here and will result in error " +"messages like \"``Error: Unknown interpreted text role \"py:func\".``\"." msgstr "" -"ある名前空間パッケージを用いる **すべての** 配布物は、 :file:`__init__.py` を" -"持っていなければなりません。もしいずれかの配布物でそうなっていなければ、名前" -"空間の論理破綻を招き、他のサブパッケージをインポートすることができなくなるで" -"しょう。 :file:`__init__.py` に他のコードを追加しても、それはアクセスできない" -"ものとなるでしょう。" +":doc:`ディレクティブ ` と :doc:`" +"ロール ` (例えば \"``:py:func:" +"`getattr```\" や \"``:ref:`my-reference-label```\") のように docstrings 内で" +"使われる Sphinx 拡張はこの場所では使用を許されず、 ``Error: テキストロール " +"\"py:func\" が見つかりません。`` " +"といったエラーメッセージを出すことになります。" -#: ../source/guides/packaging-namespace-packages.rst:207 +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 msgid "" -"A complete working example of two pkgutil-style namespace packages can be " -"found in the `pkgutil namespace example project`_." +"You can check your README for markup errors before uploading as follows:" msgstr "" -"pkgutil 型の名前空間パッケージのふたつの動作例が `pkgutil 型名前空間を例示す" -"るプロジェクト`_ にあります。" - -#: ../source/guides/packaging-namespace-packages.rst:217 -msgid "pkg_resources-style namespace packages" -msgstr "pkg_resources 型名前空間パッケージ" +"README ファイルのマークアップに関するエラーをアップロードする前に確認するに" +"は、次のようにします:" -#: ../source/guides/packaging-namespace-packages.rst:219 +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 msgid "" -":doc:`Setuptools ` provides the `pkg_resources." -"declare_namespace`_ function and the ``namespace_packages`` argument to :" -"func:`~setuptools.setup`. Together these can be used to declare namespace " -"packages. While this approach is no longer recommended, it is widely present " -"in most existing namespace packages. If you are creating a new distribution " -"within an existing namespace package that uses this method then it's " -"recommended to continue using this as the different methods are not cross-" -"compatible and it's not advisable to try to migrate an existing package." +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" msgstr "" -":doc:`Setuptools ` は、 `pkg_resources.declare_namespace`_ " -"関数と :func:`~setuptools.setup` に渡す ``namespace_packages`` 引数を提供しま" -"す。これらを一緒に使うことで名前空間パッケージを宣言することができます。この" -"手法はもはや推奨されていませんが、既存の名前空間パッケージのほとんどで使われ" -"ています。この手法を採用している既存の名前空間パッケージの中に新しい配布物を" -"作成する時には、異なる手法が相互に互換ではないために既存パッケージを移植しよ" -"うとすることが推奨されていないので、この手法を採用し続けることを推奨します。" +"最新版の `twine `_ をインストールします; バー" +"ジョン 1.12.0 またはそれ以上のものが必須です:" -#: ../source/guides/packaging-namespace-packages.rst:228 +#: ../source/guides/making-a-pypi-friendly-readme.rst:121 msgid "" -"To create a pkg_resources-style namespace package, you need to provide an :" -"file:`__init__.py` file for the namespace package:" +"Build the sdist and wheel for your project as described under :ref:" +"`Packaging Your Project`." msgstr "" -"pkg_resources 型名前空間パッケージを作成するには、名前空間パッケージ用の :" -"file:`__init__.py` を準備する必要があります:" +":ref:`あなたのプロジェクトをパッケージする ` に記述さ" +"れているように、プロジェクトの sdist と wheel をビルドします。" -#: ../source/guides/packaging-namespace-packages.rst:254 +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "sdist と wheel に対して ``twine check`` を実行します:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:130 msgid "" -"Some older recommendations advise the following in the namespace package :" -"file:`__init__.py`:" +"This command will report any problems rendering your README. If your markup " +"renders fine, the command will output ``Checking distribution FILENAME: " +"Passed``." msgstr "" -"いくつかの古めの推奨では、次のような名前空間パッケージ用 :file:`__init__.py` " -"を使うように言っています:" +"このコマンドは README のレンダリングに関する問題があれば報告するでしょう。" +"マークアップのレンダリングに問題がなければ、 ``配布物を検査しています " +"FILENAME: 合格 `` と出力するでしょ" +"う。" -#: ../source/guides/packaging-namespace-packages.rst:264 +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "PyPI.org へ移設する" + +#: ../source/guides/migrating-to-pypi-org.rst:8 +#: ../source/guides/multi-version-installs.rst:8 +#: ../source/guides/supporting-multiple-python-versions.rst:9 +#: ../source/guides/supporting-windows-using-appveyor.rst:7 +msgid "Obsolete" +msgstr "古い情報" + +#: ../source/guides/migrating-to-pypi-org.rst:10 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 " -"advisable because pkgutil and pkg_resources-style namespace packages are not " -"cross-compatible. If the presence of setuptools is a concern then the " -"package should just explicitly depend on setuptools via ``install_requires``." +":term:`pypi.org` is the new, rewritten version of PyPI that has replaced the " +"legacy PyPI code base. It is the default version of PyPI that people are " +"expected to use. These are the tools and processes that people will need to " +"interact with ``PyPI.org``." msgstr "" -"背景にあるアイデアとしては、 setuptools を使えないような稀な場合には、パッ" -"ケージを pkgutil 型パッケージに切り戻したいと言うことがあるかもしれません。 " -"pkgutil 型と pkg_resources 型の名前空間パッケージは互いに非互換なので、これは" -"推奨できるものではありません。 setuptool が存在するか否かが問題なのであれば、" -"パッケージとしては ``install_requires`` を通じて setuptools に明示的に依存す" -"ると示しておくべきです。" +":term:`pypi.org` は、新しくて書き直されたバージョンの PyPI で、以前の PyPI " +"コードベースを置き換えるものです。みなさんが普通はこれを使うものと期待されて" +"いるバージョンの PyPI です。 ``PyPI.org`` とやり取りするためのツールや手順が" +"あります。" -#: ../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:" +#: ../source/guides/migrating-to-pypi-org.rst:16 +msgid "Publishing releases" +msgstr "リリースを公開する" + +#: ../source/guides/migrating-to-pypi-org.rst:18 +msgid "``pypi.org`` is the default upload platform as of September 2016." msgstr "" -"最後に、それぞれの配布物は :file:`setup.py` の :func:`~setuptools.setup` 向け" -"に ``namespace_packages`` 引数を準備しておく必要があります。例えば:" +"2016年9月以降、 ``pypi.org`` がデフォルトのアップロードプラットフォームです。" -#: ../source/guides/packaging-namespace-packages.rst:285 +#: ../source/guides/migrating-to-pypi-org.rst:20 msgid "" -"A complete working example of two pkg_resources-style namespace packages can " -"be found in the `pkg_resources namespace example project`_." +"Uploads through ``pypi.python.org`` were *switched off* on **July 3, 2017**. " +"As of April 13th, 2018, ``pypi.org`` is the URL for PyPI." msgstr "" -"pkg_resources 型の名前空間パッケージの動作可能な二つの例が `pkg_resources 型" -"名前空間例示プロジェクト`_ で見つかるはずです。" +"``pypi.python.org`` を通じたアップロードは **2017年7月3日** に使用不可能にな" +"りました。2018年4月13日以降は、``pypi.org`` が PyPI のURLです。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +#: ../source/guides/migrating-to-pypi-org.rst:23 msgid "" -"Publishing package distribution releases using GitHub Actions CI/CD workflows" +"The recommended way to migrate to PyPI.org for uploading is to ensure that " +"you are using a new enough version of your upload tool." msgstr "" -"GitHub Actions CI/CD ワークフローを用いてパッケージ配布物のリリースを公開する" +"PyPI.org へ移行するためのアップロードでは、アップロードに使うツールが十分に新" +"しいバージョンのものであることを確実にしておくことが推奨されます。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +#: ../source/guides/migrating-to-pypi-org.rst:26 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`_ for publishing. It also uses " -"GitHub's `upload-artifact`_ and `download-artifact`_ actions for temporarily " -"storing and downloading the source packages." +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" msgstr "" -"`GitHub Actions CI/CD`_ を使うと、 GitHub プラットフォームで何かイベントが発" -"生するたびに一連のコマンドを実行することができます。よくある選択のひとつは、 " -"``push`` イベントを引き金にしてあるワークフローを行うというものです。このガイ" -"ドでは、タグ付きのコミットが push されるたびに Python 配布物を公開するやり方" -"をお見せします。それには `pypa/gh-action-pypi-publish GitHub Action`_ を使っ" -"て出版 します。また、一時的な格納やソースコード配布物のダウンロード" -"のためにGitHubの `upload-artifact`_ と `download-artifact`_ を使います。" +"``pypi.org`` に転換するためのデフォルトのアップロード設定は次のようなバージョ" +"ンです:" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:19 -msgid "" -"This guide *assumes* that you already have a project that you know how to " -"build distributions for and *it lives on GitHub*. This guide also avoids " -"details of building platform specific projects. If you have binary " -"components, check out :ref:`cibuildwheel`'s GitHub Action examples." +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" msgstr "" -"このガイドでは、配布物をビルドするやり方を知っているプロジェクトが既にそんざ" -"いして、それが *GitHub に置いてある* ことを *前提* にしています。このガイド" -"は、また、特定のプロジェクトをビルドするプラットフォームの詳細に立ち入ること" -"はしません。もしあなたがバイナリのコンポーネントを持っているなら、 :ref:" -"`cibuildwheel` にある GitHub Action の例を調べてみてください。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:25 -msgid "Configuring trusted publishing" -msgstr "信頼された出版 を設定する" +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:27 +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "Python 2.7.13 (``distutils`` 更新)" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "Python 3.4.6 (``distutils`` 更新)" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "Python 3.5.3 (``distutils`` 更新)" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "Python 3.6.0 (``distutils`` 更新)" + +#: ../source/guides/migrating-to-pypi-org.rst:35 msgid "" -"This guide relies on PyPI's `trusted publishing`_ implementation to connect " -"to `GitHub Actions CI/CD`_. This is recommended for security reasons, since " -"the generated tokens are created for each of your projects individually and " -"expire automatically. Otherwise, you'll need to generate an `API token`_ for " -"both PyPI and TestPyPI. In case of publishing to third-party indexes like :" -"doc:`devpi `, you may need to provide a username/password " -"combination." +"In addition to ensuring you're on a new enough version of the tool for the " +"tool's default to have switched, you must also make sure that you have not " +"configured the tool to override its default upload URL. Typically this is " +"configured in a file located at :file:`$HOME/.pypirc`. If you see a file " +"like:" msgstr "" -"このガイド文書は、`GitHub Actions CI/CD`_ に接続するために PyPI の `信頼ある" -"出版`_ の実装に依存しています。これは、生成されるトークンが各プロジェクトでそ" -"れぞれ独立に作成されて自動的に期限切れになるというセキュリティ上の理由から推" -"奨されています。さもなければ、 PyPI と TestPyPI の両方について `API トークン" -"`_ を生成する必要があるでしょう。:doc:`devpi ` のような第三者" -"パーティのインデックス向けに出版 する場合には、ユーザ名とパスワード" -"の組み合わせを提供する必要があるかもしれません。" +"ツールのデフォルト設定が切り替わっている程に十分に新しいツールを使っているこ" +"とを確認するのに加えて、そのデフォルトのアップロード先 URL を上書きするような" +"設定をしていないことを確実にしてください。これは典型的には file:`$HOME/." +"pypirc` で設定されています。もしこんなファイルを目にするようであれば:" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +#: ../source/guides/migrating-to-pypi-org.rst:52 msgid "" -"Since this guide will demonstrate uploading to both PyPI and TestPyPI, we'll " -"need two trusted publishers configured. The following steps will lead you " -"through creating the \"pending\" publishers for your new :term:`PyPI project " -"`. However it is also possible to add `trusted publishing`_ to any " -"pre-existing project, if you are its owner." +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." msgstr "" -"このガイドではPyPIとTestPyPIの両方へのアップロードを実証しますので、ふたつの" -"信頼あるパブリッシャが設定されていることが必要になるでしょう。以下に示すス" -"テップによって、新しい :term:`PyPI プロジェクト ` 用の \" ペンディン" -"グされた\" パブリッシャ群を作成する手順を一通りお見せします。しかしながら、あ" -"なたが所有者であるならば、任意の既存プロジェクトに `信頼ある出版`_ を追加する" -"ことが可能でもあります。" +"その時は、 ``repository`` で始まる行を削除するだけで、アップロードツールのデ" +"フォルト URL を使うようになります。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +#: ../source/guides/migrating-to-pypi-org.rst:55 msgid "" -"If you followed earlier versions of this guide, you have created the secrets " -"``PYPI_API_TOKEN`` and ``TEST_PYPI_API_TOKEN`` for direct PyPI and TestPyPI " -"access. These are obsolete now and you should remove them from your GitHub " -"repository and revoke them in your PyPI and TestPyPI account settings in " -"case you are replacing your old setup with the new one." +"If for some reason you're unable to upgrade the version of your tool to a " +"version that defaults to using PyPI.org, then you may edit :file:`$HOME/." +"pypirc` and include the ``repository:`` line, but use the value ``https://" +"upload.pypi.org/legacy/`` instead:" msgstr "" -"このガイドの以前のバージョンを読み通したことがあるのであれば、PyPI や " -"TestPyPI への直接のアクセスをするために ``PYPI_API_TOKEN`` と " -"``TEST_PYPOI_API_TOKEN`` という秘密のトークンを作成したことでしょう。今ではこ" -"れらは過去のものとなっていて、旧来の設定を新しいものに置き換える際に GitHub " -"リポジトリから削除し、 PyPI や TestPyPI のアカウント設定から取り除くべきで" -"す。" +"なんらかの事情でPyPI.orgをデフォルトで使うところまでアップロードツールのバー" +"ジョンを上げられないのであれば、 :file:`$HOME/.pypirc` で ``repository:`` 行" +"が ``https://upload.pypi.org/legacy/`` を指すように編集しても構いません。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:51 -msgid "Let's begin! 🚀" -msgstr "始めましょう! 🚀" +#: ../source/guides/migrating-to-pypi-org.rst:71 +msgid "" +"(``legacy`` in this URL refers to the fact that this is the new server " +"implementation's emulation of the legacy server implementation's upload API.)" +msgstr "" +"(この URL の中の ``legacy`` は、新しいサーバ実装が、以前のサーバ実装のアップ" +"ロード API をエミュレートしているという事実を示しています。)" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:53 -msgid "Go to https://pypi.org/manage/account/publishing/." -msgstr "https://pypi.org/manage/account/publishing/ へ行く。" +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "パッケージの名前とメタデータを登録する" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +#: ../source/guides/migrating-to-pypi-org.rst:79 msgid "" -"Fill in the name you wish to publish your new :term:`PyPI project ` " -"under (the ``name`` value in your ``setup.cfg`` or ``pyproject.toml``), the " -"GitHub repository owner's name (org or user), and repository name, and the " -"name of the release workflow file under the ``.github/`` folder, see :ref:" -"`workflow-definition`. Finally, add the name of the GitHub Environment " -"(``pypi``) we're going set up under your repository. Register the trusted " -"publisher." +"Explicit pre-registration of package names with the ``setup.py register`` " +"command prior to the first upload is no longer required, and is not " +"currently supported by the legacy upload API emulation on PyPI.org." msgstr "" -"新しい :term:`PyPI プロジェクト ` 向けに発行したいと思う名前を " -"(``setup.cfg`` か ``pyproject.toml`` の中の ``名称 `` の値として)、" -"GitHub のリポジトリ所有者の名称 (org または user) と、リポジトリの名称と、 " -"``.github/`` フォルダの下のリリースワークフローの名称を記入するには、 :ref:`" -"ワークフロー定義 ` をみてください。最後に、これからリポ" -"ジトリ内に設定しようとするGutHub 環境 (``pypi``) の名称を追加してください。ト" -"ラステッドパブリッシャを登録してください。" +"初回のアップロードに先立って ``setup.py register`` コマンドでパッケージの名前" +"を明示的に先行登録する必要がなくなり、PyPI.org における以前のアップロード " +"API のエミュレーションではサポートされなくなりました。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +#: ../source/guides/migrating-to-pypi-org.rst:83 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." +"As a result, attempting explicit registration after switching to using PyPI." +"org for uploads will give the following error message::" msgstr "" -"ここで https://test.pypi.org/manage/account/publishing/ へ行って第２のステッ" -"プを繰り返してください、ただし、今回は GitHub 環境の名称として ``testpypi`` " -"を入力します。" +"その結果、アップロードに PyPI.org を使うように切り替えた後は明示的な登録の試" +"行は次のエラーメッセージを返すでしょう::" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +#: ../source/guides/migrating-to-pypi-org.rst:88 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." +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." msgstr "" -"ペンディングされたパブリッシャは今やその初回使用の準備ができており、初回使用" -"を行えば自動的にあなたのプロジェクトを生成します。" +"解決方法は登録の段階を飛ばしていきなり作品のアップロードへと進むことです。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "TestPyPI を使う" + +#: ../source/guides/migrating-to-pypi-org.rst:95 msgid "" -"If you don't have a TestPyPI account, you'll need to create it. It's not the " -"same as a regular PyPI account." +"Legacy TestPyPI (testpypi.python.org) is no longer available; use `test.pypi." +"org `_ instead. If you use TestPyPI, you must update " +"your :file:`$HOME/.pypirc` to handle TestPyPI's new location, by replacing " +"``https://testpypi.python.org/pypi`` with ``https://test.pypi.org/legacy/``, " +"for example:" msgstr "" -"TestPyPI のアカウントを持っていなければ、新たに作成する必要があります。これは" -"通常の PyPI のアカウントとは別のものです。" +"以前からの TestPyPI (testpypi.python.org) はもはや利用できませんので、代わり" +"に `test.pypi.org `_ を使ってください。 TestPyPI を使" +"うのであれば、 :file:`$HOME/.pypirc` で ``https://testpypi.python.org/pypi`` " +"を ``https://test.pypi.org/legacy/`` に置き換えるなどして、 TestPyPI の新しい" +"場所を使うように設定しなければなりません。例えば:" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:78 +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "新しいユーザアカウントを登録する" + +#: ../source/guides/migrating-to-pypi-org.rst:119 msgid "" -"For security reasons, you must require `manual approval `_ on each run for " -"the ``pypi`` environment." +"In order to help mitigate spam attacks against PyPI, new user registration " +"through ``pypi.python.org`` was *switched off* on **February 20, 2018**. New " +"user registrations at ``pypi.org`` are open." msgstr "" -"セキュリティ上の理由から、``pypi`` 環境での実行の度に、 `手動での承認 " -"`_ を要求しなければなりません。" +"PyPI に対するスパム攻撃を緩和する補助するために、 ``pypi.python.org`` におけ" +"る新規ユーザ登録は **2018年2月20日** に *終了* しました。 ``pypi.org`` での新" +"規ユーザ登録が始まっています。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 -msgid "Creating a workflow definition" -msgstr "ワークフロー定義を作成する" +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "パッケージを一覧する" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +#: ../source/guides/migrating-to-pypi-org.rst:127 msgid "" -"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" -"workflows/`` directory of your repository." +"While ``pypi.python.org`` is may still be used in links from other PyPA " +"documentation, etc, the default interface for browsing packages is ``pypi." +"org``. The domain pypi.python.org now redirects to pypi.org, and may be " +"disabled sometime in the future." msgstr "" -"GitHub CI/CD ワークフローは、リポジトリの ``.github/workflows/`` ディレクトリ" -"に置かれた YAML ファイルで宣言されます。" +"``pypi.python.org`` が他の PyPA 説明文書などからのリンクに使われているとして" +"も、パッケージを一覧するデフォルトのインタフェイスは ``pypi.org`` です。pupi." +"python.org ドメイン名は今は pypi.org へリダイレクトされていて、いつか将来の時" +"点で無効にされるでしょう。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 -msgid "Let's create a ``.github/workflows/publish-to-test-pypi.yml`` file." +#: ../source/guides/migrating-to-pypi-org.rst:134 +msgid "Downloading packages" +msgstr "パッケージをダウンロードする" + +#: ../source/guides/migrating-to-pypi-org.rst:136 +msgid "``pypi.org`` is the default host for downloading packages." msgstr "" -"``.github/workflows/publish-to-test-pypi.yml`` ファイルを作成しましょう。" +"``pypi.org`` が、パッケージをダウンロードする際のデフォルトのホストです。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "公開済みパッケージとリリースを管理する" + +#: ../source/guides/migrating-to-pypi-org.rst:141 msgid "" -"Start it with a meaningful name and define the event that should make GitHub " -"run this workflow:" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." msgstr "" -"意味のある名前で始めて、 GitHub がこのワークフローを走らせるべきイベントを定" -"義しましょう:" +"``pypi.org`` では、ログインしたユーザが自分が公開したプロジェクトやリリースに" +"ついて管理するための全機能を提供しています。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:101 -msgid "Checking out the project and building distributions" -msgstr "プロジェクトをチェックアウトして配布物をビルドする" +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "どうすれば ``setup.py`` ベースのプロジェクトを近代化できるでしょうか？" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "``pyproject.toml`` を追加するべきですか？" + +#: ../source/guides/modernize-setup-py-project.rst:12 msgid "" -"We will have to define two jobs to publish to PyPI and TestPyPI " -"respectively, and an additional job to build the distribution packages." +"A :term:`pyproject.toml` file is strongly recommended. The presence of a :" +"file:`pyproject.toml` file itself does not bring much. [#]_ What is actually " +"strongly recommended is the ``[build-system]`` table in :file:`pyproject." +"toml`." msgstr "" -"PyPI と TestPyPI に向けて出版 するためには、二つのジョブを定義しな" -"ければならず、また、配布物のパッケージ群をビルドするための追加のジョブも定義" -"しなければなりません。" +":term:`pyproject.toml` ファイルは強く推奨されています。:file:`pyproject." +"toml` ファイルが存在すること自体は多くをもたらすものではありません。 [#]_ 実" +"際に強く推奨されているものは、:file:`pyproject.toml` の中の ``[build-" +"system]`` テーブルです。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +#: ../source/guides/modernize-setup-py-project.rst:16 msgid "" -"First, we'll define the job for building the dist packages of your project " -"and storing them for later use:" +"Note that it has influence on the build isolation feature of pip, see below." msgstr "" -"最初に、あなたのプロジェクトの dist パッケージをビルドして、その後の使用のた" -"めに保存するジョブを定義しましょう:" +"以下のように、これが pip のビルド隔離機能に影響を与えるということを銘記してく" +"ださい。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +#: ../source/guides/modernize-setup-py-project.rst:23 msgid "" -"This will download your repository into the CI runner and then install and " -"activate the newest available Python 3 release." +"No, :file:`setup.py` can exist in a modern :ref:`setuptools` based project. " +"The :term:`setup.py` file is a valid configuration file for setuptools that " +"happens to be written in Python. However, the following commands are " +"deprecated and **MUST NOT** be run anymore, and their recommended " +"replacement commands should be used instead:" msgstr "" -"これによって、あなたのリポジトリを CI ランナーにダウンロードして、利用可能な" -"最新の Python 3 リリースをインストールしアクティベートすることになります。" +"いいえ、 :file:`setup.py` は、近代的な :ref:`setuptools` ベースのプロジェクト" +"にあっても構いません。 :term:`setup.py` ファイルは、たまたま Python で書かれ" +"ている setuptools 向けの正当な設定ファイルなのです。しかしながら、以下のコマ" +"ンド群は非推奨になっていてもはや実行することは **許されず** 、その代わりに以" +"下のようなコマンドを使用するべきです:" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "``python -m build``" + +#: ../source/guides/modernize-setup-py-project.rst:42 +#: ../source/guides/modernize-setup-py-project.rst:66 +#: ../source/guides/modernize-setup-py-project.rst:111 +#: ../source/guides/modernize-setup-py-project.rst:129 +#: ../source/guides/modernize-setup-py-project.rst:221 +msgid "For more details:" +msgstr "より詳しくは:" + +#: ../source/guides/modernize-setup-py-project.rst:44 +msgid ":ref:`setup-py-deprecated`" +msgstr ":ref:`setup-py-deprecated`" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "どこから始めましょうか？" + +#: ../source/guides/modernize-setup-py-project.rst:50 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:" +"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 "" -"そして、今や我々はソースコードから dist 配布物をビルドして保存しておくことが" -"できます。この例では、パッケージを ``build`` することになります。ですから、こ" -"れをステップリストに加えましょう:" - -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 -msgid "Defining a workflow job environment" -msgstr "ワークフローのジョブ環境を定義する" +":term:`プロジェクト ` のソースコードツリーのルート部分には、次に示す" +"ように、 ``[build-system]`` テーブルを含む :file:`pyproject.toml` がなければ" +"なりません:" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:130 +#: ../source/guides/modernize-setup-py-project.rst:60 msgid "" -"Now, let's add initial setup for our job that will publish to PyPI. It's a " -"process that will execute commands that we'll define later. In this guide, " -"we'll use the latest stable Ubuntu LTS version provided by GitHub Actions. " -"This also defines a GitHub Environment for the job to run in its context and " -"a URL to be displayed in GitHub's UI nicely. Additionally, it allows " -"acquiring an OpenID Connect token that the ``pypi-publish`` actions needs to " -"implement secretless trusted publishing to PyPI." +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." msgstr "" -"さて、PyPI へ発行 される予定のジョブに初期設定を追加しましょう。そ" -"れは、後ほど定義するであろうコマンドを実行するプロセスになるでしょう。このガ" -"イド文書では、" +"これは、 :term:`ビルドフロントエンド ` にこのプロジェクトの :" +"term:`ビルドバックエンド ` は :ref:`setuptools` だと知らせるた" +"めの標準化されたやり方です。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:144 +#: ../source/guides/modernize-setup-py-project.rst:63 msgid "" -"This will also ensure that the PyPI publishing workflow is only triggered if " -"the current commit is tagged." +"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 "" -"これは、当該コミットがタグ付きである時にだけ PyPI 公開 ワークフ" -"ローが起動されることをも保証するものです。" +"(空のファイルであっても) :file:`pyproject.toml` ファイルが存在していれば、 :" +"ref:`pip` が *ビルド隔離 * を取り扱うデフォルトの動きが変わ" +"ることに注意してください。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 -msgid "Publishing the distribution to PyPI" -msgstr "PyPI へ配布物を公開する " +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr ":ref:`配布パッケージ `" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:150 -msgid "Finally, add the following steps at the end:" -msgstr "最後に、次の手続きを末尾に追加しましょう:" +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr ":ref:`pyproject-build-system-table`" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system/pyproject-toml`" +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 "追加的なビルド時の依存関係をどのように扱うのですか？" + +#: ../source/guides/modernize-setup-py-project.rst:76 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." +"On top of setuptools itself, if :file:`setup.py` depends on other third-" +"party libraries (outside of Python's standard library), those must be listed " +"in the ``requires`` list of the ``[build-system]`` table, so that the build " +"frontend knows to install them when building the :term:`distributions " +"`." msgstr "" -"この手順では、保存されている配布パッケージが `download-artifact`_ アクション" -"によってダウンロードされた後に `pypa/gh-action-pypi-publish`_ という GitHub " -"Action: を使って、 ``dist/`` フォルダの内容物を無条件に PyPI へアップロードし" -"ます。" +"setuptools それ自体の上に、もし :file:`setup.py` が他の (Python の標準ライブ" +"ラリの外側の) 第三者のライブラリに依存しているのであれば、 :term:`配布物 " +"` をビルドする際にビルドフロトンエンドがそれらをインス" +"トールする必要があることを知るために、 ``[build-system]`` テーブルの " +"``require`` リストに挙げられていなければなりません。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:163 -msgid "Signing the distribution packages" -msgstr "配布パッケージに署名する" +#: ../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 "例えば、このような :file:`setup.py` ファイルがあれば:" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:165 +#: ../source/guides/modernize-setup-py-project.rst:99 msgid "" -"The following job signs the distribution packages with `Sigstore`_, the same " -"artifact signing system `used to sign CPython `_." +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" msgstr "" -"以下に述べるジョブは、`CPython ` " -"に署名するのに使われる`_ ものと同じアーティファクトである `Sigstore`_ を使っ" -"て配布パッケージに署名します。" +":file:`pyproject.toml` ファイルはこのようであることが要求されます (:file:" +"`setup.py` には変更なし):" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:168 +#: ../source/guides/modernize-setup-py-project.rst:117 +msgid "What is the build isolation feature?" +msgstr "ビルド隔離機能とは何でしょうか？" + +#: ../source/guides/modernize-setup-py-project.rst:119 msgid "" -"Firstly, it uses the `sigstore/gh-action-sigstore-python GitHub Action`_ to " -"sign the distribution packages. In the next step, an empty GitHub Release " -"from the current tag is created using the ``gh`` CLI. Note this step can be " -"further customised. See the `gh release documentation `_ as a reference." +"Build frontends typically create an ephemeral virtual environment where they " +"install only the build dependencies (and their dependencies) that are listed " +"under ``build-system.requires`` and trigger the build in that environment." msgstr "" -"第一に、配布物パッケージに署名するのに `sigstore/gh-action-sigstore-python " -"GitHub Action`_ を使います。次の段階では、現在のタグから空の GitHub Release " -"が``hg`` CLI を使って作成されます。この段階をさらにカスタマイズすることができ" -"る点に留意してください。リファレンスとしては、`gh リリース説明文書 `_ を見てください。" +"典型的な場合、ビルドフロントエンドは、 ``build-system.requires`` の下に列挙さ" +"れているビルド時の依存関係 (と、その依存関係)だけをインストールする先としての" +"一時的な仮想環境を作成し、その環境内でビルドを開始します。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:176 +#: ../source/guides/modernize-setup-py-project.rst:124 msgid "" -"You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating " -"the GitHub Release. See the `GitHub documentation `_ for " -"instructions. Specifically, the token needs the ``contents: write`` " -"permission." +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" msgstr "" -"GitHub リリースの作成ができるような ``GITHUB_TOKEN`` パーミッションを維持する" -"必要があります。やり方については、 `GitHub 説明文書 `_ を見てくださ" -"い。具体的に言えば、トークンには ``contents: write`` 権限が必要です。" +"この隔離が不要な一部のプロジェクト向けには、以下のようにすれば (隔離を) 非活" +"性化することができます:" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:182 -msgid "Finally, the signed distributions are uploaded to the GitHub Release." -msgstr "最後に、署名された配布物が GitHub Release へアップロードされます。" +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "``python -m build --no-isolation``" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "``python -m pip install --no-build-isolation``" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "パッケージのメタデータをどのように扱えば良いでしょうか？" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:192 +#: ../source/guides/modernize-setup-py-project.rst:137 msgid "" -"This is a replacement for GPG signatures, for which support has been " -"`removed from PyPI `_. " -"However, this job is not mandatory for uploading to PyPI and can be omitted." +"All static metadata can optionally be moved to a ``[project]`` table in :" +"file:`pyproject.toml`." msgstr "" -"これは、 `PyPI から削除された `_ GPG 署名を代替するものです。しかしながら、このジョブは PyPI " -"へアップロードする時に必須のものと言うわけではなく、省略することもできます。" - -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 -msgid "Separate workflow for publishing to TestPyPI" -msgstr "TestPyPI へ公開 するもうひとつのワークフロー" +"静的なメタデータはすべて、 :file:`pyproject.toml` の ``[project]`` テーブルへ" +"移しても構いません。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 -msgid "" -"Now, repeat these steps and create another job for publishing to the " -"TestPyPI package index under the ``jobs`` section:" +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" msgstr "" -"さて、これらのステップを繰り返して、 ``jobs`` セクションに TestPyPI パッケー" -"ジインデックスに公開 するようなもうひとつのジョブを作成しましょう:" +"このように :file:`pyproject.toml` ファイルで完全に置き換えることも可能です:" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:210 +#: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Requiring manual approvals in the ``testpypi`` GitHub Environment is " -"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." +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." msgstr "" -"``testpypi`` Github 環境において手動の承認を要求することは、main ブランチへの" -"コミット毎に走るように設計されていることから、典型的な場合には不必要とされて" -"いて、使われるとすればリリースの公開 パイプラインが健全であることを" -"示すためであることが多いのです。" +"``[project]`` テーブルで許される内容の完全な仕様については、 :ref:" +"`` を読んでください。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:214 -msgid "The whole CI/CD workflow" -msgstr "CI/CD ワークフローの全体像" +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "動的なメタデータをどのように取り扱いますか？" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +#: ../source/guides/modernize-setup-py-project.rst:171 msgid "" -"This paragraph showcases the whole workflow after following the above guide." +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." msgstr "" -"この段落には、上述のガイド文書に従った場合のワークフローの全体像を披露しま" -"す。" +"パッケージングであるメタデータフィールドが静的ではないならば、 ``[project]`` " +"テーブルの ``dynamic`` に列挙する必要があります。" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:224 -msgid "That's all, folks!" -msgstr "これでできましたよ、皆さん!" +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "以下のように近代化することができるでしょう:" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:226 -msgid "" -"Now, whenever you push a tagged commit to your Git repository remote on " -"GitHub, this workflow will publish it to PyPI. And it'll publish any push to " -"TestPyPI which is useful for providing test builds to your alpha users as " -"well as making sure that your release pipeline remains healthy!" +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" msgstr "" -"これで、手元の Git リポジトリをリモートの GitHub にタグ付きのコミットをプッ" -"シュする時はいつでも、このワークフローがそれを PyPI へ公開します。そして、" -"プッシュしさえすればいつでも TestPyPI で公開されますので、アルファ版のユーザ" -"にテストビルドを提供するためにも、あなたのリリースパイプラインが健全な状態に" -"保たれていることを確認するためにも役に立ちます!" +":ref:`プロジェクトのメタデータを動的であると宣言する `" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:234 -msgid "" -"If your repository has frequent commit activity and every push is uploaded " -"to TestPyPI as described, the project might exceed the `PyPI project size " -"limit `_. The limit could be " -"increased, but a better solution may constitute to use a PyPI-compatible " -"server like :ref:`pypiserver` in the CI for testing purposes." +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" msgstr "" -"リポジトリで活発に頻繁なコミットがあって、前述のようにあらゆるプッシュが " -"TestPyPI へアップロードされているなら、そのプロジェクトは `PyPI プロジェクト" -"サイズ制限 `_ を超過するかもしれま" -"せん。この制限を緩和することもできますが、より良い解決策は試験目的の CI の中" -"で :ref:`pypiserver` のような PyPI と互換のあるサーバを使うように構成すること" -"かもしれません。" +"変更不能ななにかが ``setup.py`` ファイルがあるものと期待していたらどうします" +"か？" -#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:242 +#: ../source/guides/modernize-setup-py-project.rst:229 msgid "" -"It is recommended to keep the integrated GitHub Actions at their latest " -"versions, updating them frequently." +"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 "" -"統合された GitHub Actions を最新版に保ち、頻繁にアップデートすることを推奨し" -"ます。" - -#: ../source/guides/section-build-and-publish.rst:3 -msgid "Building and Publishing" -msgstr "ビルドすることと公開すること" - -#: ../source/guides/section-hosting.rst:3 -msgid "Hosting" -msgstr "ホスティング" +"例えば、簡単には変更することができないプロセスが存在していて、それが " +"``python setup.py --name`` のようなコマンドの実行を必要としてる場合。" -#: ../source/guides/section-install.rst:3 -msgid "Installation" -msgstr "インストール" +#: ../source/guides/modernize-setup-py-project.rst:232 +msgid "" +"It is perfectly fine to leave a :file:`setup.py` file in the project source " +"tree even after all its content has been moved to :file:`pyproject.toml`. " +"This file can be as minimalistic as this:" +msgstr "" +"たとえ全ての内容が :file:`pyproject.toml` へ移された後であっても、プロジェク" +"トのソースコードツリーに `setup.py` を残すことは完全に問題のないことです。こ" +"のファイルの最小限の姿はこのようになります:" -#: ../source/guides/single-sourcing-package-version.rst:5 -msgid "Single-sourcing the package version" -msgstr "パッケージのバージョンを１箇所で管理する" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr ":ref:`pyproject-toml-spec`" -#: ../source/guides/single-sourcing-package-version.rst:7 -#: ../source/guides/tool-recommendations.rst:45 -msgid "Todo" -msgstr "Todo" +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr ":doc:`setuptools:build_meta`" -#: ../source/guides/single-sourcing-package-version.rst:7 -msgid "Update this page for build backends other than setuptools." -msgstr "setuptools 以外のビルドバックエンドについてこのページを更新すること。" +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "複数バージョンのインストール" -#: ../source/guides/single-sourcing-package-version.rst:9 +#: ../source/guides/multi-version-installs.rst:11 msgid "" -"There are many techniques to maintain a single source of truth for the " -"version number of your project:" +"easy_install allows simultaneous installation of different versions of the " +"same project into a single environment shared by multiple programs which " +"must ``require`` the appropriate version of the project at run time (using " +"``pkg_resources``)." msgstr "" -"プロジェクトのバージョン番号をたったひとつの真実の場所で管理するテクニックは" -"たくさん存在しています:" +"easy_install を使えば、異なるバージョンの同一プロジェクトをひとつの環境に同時" +"にインストールして、なおかつ、それぞれ動作時にプロジェクトの特定のバージョン" +"を (``pkg_resources`` での指定を通じて) ``要求 `` する複数のプログラ" +"ムをその環境で動作させることができます。" -#: ../source/guides/single-sourcing-package-version.rst:12 +#: ../source/guides/multi-version-installs.rst:16 msgid "" -"Read the file in :file:`setup.py` and get the version. Example (from `pip " -"setup.py `_)::" +"For many use cases, virtual environments address this need without the " +"complication of the ``require`` directive. However, the advantage of " +"parallel installations within the same environment is that it works for an " +"environment shared by multiple applications, such as the system Python in a " +"Linux distribution." msgstr "" -":file:`setup.py` に書かれたファイルを読み込んでバージョンを得ましょう。" -"( `pip setup.py `_ での) " -"例はこちら::" +"多くのユースケースでは、 ``require`` ディレクティブを混乱させる事なく、仮想環" +"境がこのような需要を満たします。しかしながら、同一環境内に(複数バージョンを)" +"並行してインストールすることの利点は、Linux 配布物におけるシステム側の " +"Python のように、複数のアプリケーションによって共有される環境で動作することで" +"す。" -#: ../source/guides/single-sourcing-package-version.rst:39 +#: ../source/guides/multi-version-installs.rst:22 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):" +"The major limitation of ``pkg_resources`` based parallel installation is " +"that as soon as you import ``pkg_resources`` it locks in the *default* " +"version of everything which is already available on sys.path. This can cause " +"problems, since ``setuptools`` created command line scripts use " +"``pkg_resources`` to find the entry point to execute. This means that, for " +"example, you can't use ``require`` tests invoked through ``nose`` or a WSGI " +"application invoked through ``gunicorn`` if your application needs a non-" +"default version of anything that is available on the standard ``sys.path`` - " +"the script wrapper for the main application will lock in the version that is " +"available by default, so the subsequent ``require`` call in your own code " +"fails with a spurious version conflict." msgstr "" -"setuptools 46.4.0 のリリースでは、代わりに次のものを :file:`setup.cfg` ファイ" -"ルに置くことで同じことを達成できています (\"package\" をパッケージをインポー" -"トする際の名前で置き換えてください) :" +"並行インストールに立脚した ``pkg_resources`` の主要な制限事項は、 " +"``pkg_resources`` をインポートするや否や、sys.path 上で既に利用可能なものはす" +"べてそのバージョンに *デフォルト* バージョンが固定されてしまうことです。コマ" +"ンドラインスクリプトで生成された ``setuptools`` が ``pkg_resources`` を使って" +"プログラム実行のためのエントリポイントを探索するので、これは問題を引き起こす" +"かもしれません。これが意味するところは、例えば、そのアプリケーションが、標準" +"の ``sys.path`` 上に存在するものなら何であれ、それとは異なるバージョンを必要" +"とする場合に、 ``nose`` を通じて ``require`` テストを使ったり ``gunicorn`` を" +"通じて WSGI アプリケーションを呼び出したりすることができない - メインのアプリ" +"ケーションのためのスクリプトラッパがデフォルトで利用可能なバージョンに固定さ" +"れてしまって、各アプリケーションの引き続く ``require`` 呼び出しが見せかけの" +"バージョン衝突によって失敗してしまう、ということです。" -#: ../source/guides/single-sourcing-package-version.rst:49 +#: ../source/guides/multi-version-installs.rst:34 msgid "" -"As of the release of setuptools 61.0.0, one can specify the version " -"dynamically in the project's :file:`pyproject.toml` file." +"This can be worked around by setting all dependencies in ``__main__." +"__requires__`` before importing ``pkg_resources`` for the first time, but " +"that approach does mean that standard command line invocations of the " +"affected tools can't be used - it's necessary to write a custom wrapper " +"script or use ``python3 -c ''`` to invoke the application's main " +"entry point directly." msgstr "" -"setuptools 61.0.0 のリリースの時点では、プロジェクトの :file:`pyproject." -"toml` ファイルの中にバージョンを動的に指定することができます。" +"最初に ``pkg_resources`` をインポートするよりも前に ``__main__." +"__requires__`` の中のすべての依存関係を設定しておくことでこの問題を回避するこ" +"とができますが、このアプローチでは影響を受けるツールを標準のコマンドラインか" +"らの呼び出しで使うことができないことになります - つまり、独自のラッパスクリプ" +"トを書くか、アプリケーションの main エントリポイントを直接に呼び出すための " +"``python -c ''`` を使うかしなければなりません。" -#: ../source/guides/single-sourcing-package-version.rst:61 +#: ../source/guides/multi-version-installs.rst:41 msgid "" -"Please be aware that declarative config indicators, including the ``attr:`` " -"directive, are not supported in parameters to :file:`setup.py`." +"Refer to the `pkg_resources documentation `__ for more details." msgstr "" -"``attr:`` ディレクティブを含む装飾的な設定指示子が、 :file:`setup.py` 向けの" -"パラメータとしてはサポートされていないことに注意してください。" +"さらに詳しい情報については、 `pkg_resources 説明文書 `__ を参照して" +"ください。" -#: ../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 "" -"外部のビルドツールを使う場合は、両方の場所(ロケーション)を更新できるようなも" -"の、あるいは、両方のサイトから使える API を提供しているものを使いましょう。" +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "バイナリ拡張をパッケージングする" -#: ../source/guides/single-sourcing-package-version.rst:68 -msgid "" -"Few tools you could use, in no particular order, and not necessarily " -"complete: `bump2version `_, `changes " -"`_, `commitizen `_, `zest.releaser `_." -msgstr "" -"使えるかもしれない外部のビルドツールのリスト、ただし、順不同で、ここに挙げら" -"れていなくても使えるものがあるかもしれません: `bump2version `_, `changes `_, " -"`commitizen `_, `zest.releaser `_." +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "2013-12-08" -#: ../source/guides/single-sourcing-package-version.rst:75 +#: ../source/guides/packaging-binary-extensions.rst:10 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." +"One of the features of the CPython reference interpreter is that, in " +"addition to allowing the execution of Python code, it also exposes a rich C " +"API for use by other software. One of the most common uses of this C API is " +"to create importable C extensions that allow things which aren't always easy " +"to achieve in pure Python code." msgstr "" -"プロジェクト内にグローバル変数の ``__version__`` に値を設定した専用のモジュー" -"ル (例えば :file:`version.py`) を作って :file:`setup.py` からそれを読み取っ" -"て ``exec`` で値を変数に取り込むと良いでしょう。" +"CPython の参照インタープリタの機能の一つは、Python のコードを実行することに加" +"えて、他のソフトウェアによる利用のために豊富な C の API を露出することです。" +"この C の API の最もよくある利用方法は、純粋な Python のコードでは必ずしも簡" +"単には達成できないようなことをインポート可能な C 拡張として作成することです。" -#: ../source/guides/single-sourcing-package-version.rst:86 -msgid "" -"Example using this technique: `warehouse `_." -msgstr "" -"このテクニックを使っている例: `warehouse `_ 。" +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "バイナリ拡張の概要" -#: ../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 "" -"単純に ``VERSION`` という名前のテキストファイルに値を書いておいて、 :file:" -"`setup.py` とプロジェクトのソースコードの両方から読み込みます。" +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "ユースケース" -#: ../source/guides/single-sourcing-package-version.rst:96 +#: ../source/guides/packaging-binary-extensions.rst:23 msgid "" -"An advantage with this technique is that it's not specific to Python. Any " -"tool can read the version." +"The typical use cases for binary extensions break down into just three " +"conventional categories:" msgstr "" -"このテクニックを使う利点は、Python に限定されたやり方ではないということです。" -"どんなツールでもバージョン番号を読み取ることができます。" +"バイナリ拡張の典型的なユースケースは、たった３個の伝統的なカテゴリに分類され" +"ます:" -#: ../source/guides/single-sourcing-package-version.rst:101 +#: ../source/guides/packaging-binary-extensions.rst:26 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`)." +"**accelerator modules**: these modules are completely self-contained, and " +"are created solely to run faster than the equivalent pure Python code runs " +"in CPython. Ideally, accelerator modules will always have a pure Python " +"equivalent to use as a fallback if the accelerated version isn't available " +"on a given system. The CPython standard library makes extensive use of " +"accelerator modules. *Example*: When importing ``datetime``, Python falls " +"back to the `datetime.py `_ module if the C implementation ( `_datetimemodule.c `_) is not " +"available." msgstr "" -"このやり方を採用するなら、 ``VERSION`` ファイルがすべてのソースコードとバイナ" -"リの配布物に含まれているように気を付けてください (例えば :file:`MANIFEST.in` " -"に ``include VERSION`` を追加しておくなど)。" +"**アクセラレータモジュール**: これらのモジュールは完全に自己完結型で、" +"CPython で同機能の純粋なPython コードを走らせるよりも速く動作するためにだけ作" +"成されます。アクセラレートされたバージョンが当該システム上で動作しなかった時" +"のために、アクセラレータモジュールには同機能の純粋なPythonのコードを予備品と" +"して同梱していることが理想的です。CPython の標準ライブラリはアクセラレータモ" +"ジュールを多用しています。*例*: ``datetime`` をインポートする際、C での実装 " +"(`_datetimemodule.c `_) が使えない時には、`datetime.py `_ にフォールバックします。" -#: ../source/guides/single-sourcing-package-version.rst:105 +#: ../source/guides/packaging-binary-extensions.rst:37 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." -"metadata`` was introduced in Python 3.8 and is available to older versions " -"as the ``importlib-metadata`` project.) An installed project's version can " -"be fetched with the API as follows::" +"**wrapper modules**: these modules are created to expose existing C " +"interfaces to Python code. They may either expose the underlying C interface " +"directly, or else expose a more \"Pythonic\" API that makes use of Python " +"language features to make the API easier to use. The CPython standard " +"library makes extensive use of wrapper modules. *Example*: `functools.py " +"`_ is a Python " +"module wrapper for `_functoolsmodule.c `_." msgstr "" -":file:`setup.py` に値を保存して、プロジェクトのソースコードが ``importlib." -"metadata`` API を使ってその値を動作中に取得するようにしましょう。 " -"(``importlib.metadata`` は Python 3.8 で導入されていて、それより古いバージョ" -"ンでは ``importlib-metadata`` プロジェクトとして利用可能になっています) イン" -"ストール済みのプロジェクトのバージョン番号をこの API で取り込むには次のように" -"します::" +"**ラッパモジュール**: これらのモジュールは、既存の C のインタフェースを " +"Python に見せるために作られます。それらは C のインタフェースを直接に見せる" +"か、または、Python 言語の機能を使ってAPI をより使いやすくするようなもっと " +"\"Pythonic\" なやり方で見せるかします。CPython の標準ライブラリでは、ラッパモ" +"ジュールを多用しています。 *例*: `functools.py `_ は、 `_functoolsmodule.c `_ のための" +"ラッパモジュールです。" -#: ../source/guides/single-sourcing-package-version.rst:120 +#: ../source/guides/packaging-binary-extensions.rst:45 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." +"**low-level system access**: these modules are created to access lower level " +"features of the CPython runtime, the operating system, or the underlying " +"hardware. Through platform specific code, extension modules may achieve " +"things that aren't possible in pure Python code. A number of CPython " +"standard library modules are written in C in order to access interpreter " +"internals that aren't exposed at the language level. *Example*: ``sys``, " +"which comes from `sysmodule.c `_." msgstr "" -"``importlib.metadata`` API が知っているのはインストールされたパッケージのメタ" -"データだけであって、現在インポートされているソースコードについて知っていると" -"は限らないことに注意してください。" +"**低レベルシステムアクセス**: これらのモジュールは、CPython ランタイムやオペ" +"レーティングシステム、あるいはさらに下層のハードウェアの低レベルの機能にアク" +"セスするために作成されています。プラットフォームに固有のコードを通して、純粋" +"な Python コードでは不可能なことを拡張モジュールが達成できるかもしれません。" +"結構な数の CPython の標準ライブラリモジュールが C で書かれていて、言語のレベ" +"ルには提供されていないようなインタープリタの内部にアクセスできるようになって" +"います。 *例*: ``sys`` は `sysmodule.c `_ から来ています。" -#: ../source/guides/single-sourcing-package-version.rst:124 +#: ../source/guides/packaging-binary-extensions.rst:54 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::" +"One particularly notable feature of C extensions is that, when they don't " +"need to call back into the interpreter runtime, they can release CPython's " +"global interpreter lock around long-running operations (regardless of " +"whether those operations are CPU or IO bound)." msgstr "" -"あるプロジェクトで動作中にバージョン番号を取得する方法を使っているのであれ" -"ば、Python 3.8 よりも古いバージョンを使う場合はそのプロジェクトの " -"``install_requires`` に ``importlib-metadata`` を書いておかなければなりませ" -"ん::" +"C 言語拡張の特筆すべき機能は、インタプリタランタイムにコールバックする必要の" +"ない時には、 (CPU制約であろうとIO制約であろうと関わりなく) 長時間走り続ける操" +"作を包む CPython グローバルインタプリタロックを解放することができるということ" +"です。" -#: ../source/guides/single-sourcing-package-version.rst:138 +#: ../source/guides/packaging-binary-extensions.rst:59 msgid "" -"An older (and less efficient) alternative to ``importlib.metadata`` is the " -"``pkg_resources`` API provided by ``setuptools``::" +"Not all extension modules will fit neatly into the above categories. The " +"extension modules included with NumPy, for example, span all three use cases " +"- they move inner loops to C for speed reasons, wrap external libraries " +"written in C, FORTRAN and other languages, and use low level system " +"interfaces for both CPython and the underlying operation system to support " +"concurrent execution of vectorised operations and to tightly control the " +"exact memory layout of created objects." msgstr "" -"``importlib.metadata`` に対するもっと古い (かつ、より非効率な) 代替策は、 " -"``setuptools`` が提供する ``pkg_resources`` API です::" +"必ずしも全ての拡張モジュールが上記のカテゴリにぴたりと当て嵌まる訳ではありま" +"せん。例えば NumPy に含まれる拡張モジュールは３個のカテゴリのすべてにまたがっ" +"ています - 動作速度上の理由から内側のループを C 言語に移しているし、C 言語や " +"FORTRAN 言語その他で書かれた外部のライブラリをラップしているし、また、ベクタ" +"演算の並列実行や生成したオブジェクトのメモリレイアウトを正確な管理のために、 " +"CPython とその下にあるオペレーティングシステムの両方の低レベルなシステムイン" +"ターフェイスを利用しています。" -#: ../source/guides/single-sourcing-package-version.rst:144 +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "欠点" + +#: ../source/guides/packaging-binary-extensions.rst:71 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." +"The main disadvantage of using binary extensions is the fact that it makes " +"subsequent distribution of the software more difficult. One of the " +"advantages of using Python is that it is largely cross platform, and the " +"languages used to write extension modules (typically C or C++, but really " +"any language that can bind to the CPython C API) typically require that " +"custom binaries be created for different platforms." msgstr "" -"あるプロジェクトで自分自身のバージョン番号を動作中に取得するために " -"``pkg_resources`` を使っているなら、プロジェクトの ``install_requires`` のリ" -"ストには必ず ``setuptools`` が入っていないといけません。" +"バイナリ拡張を使うことの主たる欠点は、引き続くソフトウェア配布がより難しくな" +"ることです。Python を使う利点のひとつは非常に広範囲のクロスプラットフォームで" +"ある (訳注、同一の Python コードが広範囲の異種プラットフォームで動作する) こ" +"とですが、拡張モジュールを書くのに使われる言語 (典型的には C 言語や C++ だ" +"が、実際にはどんな言語でも CPython の C 言語 API にバインドできる) は異なるプ" +"ラットフォームには異なるバイナリを作成しなければならないのが普通なのです。" -#: ../source/guides/single-sourcing-package-version.rst:148 +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "これが意味するところは、バイナリ拡張は:" + +#: ../source/guides/packaging-binary-extensions.rst:80 msgid "" -"Example using this technique: `setuptools `_." +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" msgstr "" -"このテクニックを使っている例: `setuptools `_." +"エンドユーザがソースコードからビルドできるか、または、誰かが共通のプラット" +"フォーム向けにビルド済みのバイナリを公開するか、のいずれかでなければなりませ" +"ん" -#: ../source/guides/single-sourcing-package-version.rst:151 +#: ../source/guides/packaging-binary-extensions.rst:83 msgid "" -"Set the value to ``__version__`` in ``sample/__init__.py`` and import " -"``sample`` in :file:`setup.py`." -msgstr "" -"``sample/__init__.py`` で ``__version__`` に値を設定して、 :file:`setup.py` " -"から ``sample`` をインポートしましょう。" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "CPython 参照インタプリタのビルドが異なると互換性がないかもしれません" -#: ../source/guides/single-sourcing-package-version.rst:165 +#: ../source/guides/packaging-binary-extensions.rst:86 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." +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" msgstr "" -"このテクニックはよく知られたものだが、 ``install_requires`` で定義された依存" -"先パッケージを ``sample/__init__.py`` がインポートしている場合には、そのよう" -"なパッケージは :file:`setup.py` が実行される時点ではまだインストールされてい" -"ない可能性が高いので、失敗するであろうということに注意してください。" +"PyPy ・ IronPython ・ Jython のような代替インタプリタ上では動作しないことがし" +"ばしばです" -#: ../source/guides/single-sourcing-package-version.rst:171 +#: ../source/guides/packaging-binary-extensions.rst:89 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 " -"there using `setuptools_scm `_." +"if handcoded, make maintenance more difficult by requiring that maintainers " +"be familiar not only with Python, but also with the language used to create " +"the binary extension, as well as with the details of the CPython C API." msgstr "" -"ソースコード内ではなくバージョンコントロールシステム (Git, Mercurialなど) の" -"タグの中にバージョン番号を保持して、そこから `setuptools_scm `_ を使って取り出しましょう。" - -#: ../source/guides/supporting-multiple-python-versions.rst:7 -msgid "Supporting multiple Python versions" -msgstr "複数の Python バージョンをサポートする" - -#: ../source/guides/supporting-multiple-python-versions.rst:10 -msgid "2014-12-24" -msgstr "2014-12-24" +"もしハードコードされているなら、メンテナンス担当者が Python のみならずそのバ" +"イナリ拡張を作成するために使われている言語についてもCPython の C 言語 API に" +"ついても慣れ親しんでいることが要求されるので、メンテナンスがより難しくなるで" +"しょう。" -#: ../source/guides/supporting-multiple-python-versions.rst:36 +#: ../source/guides/packaging-binary-extensions.rst:94 msgid "" -"In addition to the work required to create a Python package, it is often " -"necessary that the package must be made available on different versions of " -"Python. Different Python versions may contain different (or renamed) " -"standard library packages, and the changes between Python versions 2.x and 3." -"x include changes in the language syntax." +"if a pure Python fallback implementation is provided, make maintenance more " +"difficult by requiring that changes be implemented in two places, and " +"introducing additional complexity in the test suite to ensure both versions " +"are always executed." msgstr "" -"Python パッケージを作成するのに必要とされる仕事に加えて、しばしばそのパッケー" -"ジが異なるバージョンの Python に対応することが求められます。 Python のバー" -"ジョンが異なると、異なる (または名称を変更した) 標準ライブラリパッケージを含" -"むことがあり、 Python 2.x と 3.x の間には言語の文法に違いがあります。" +"純粋な Python で書かれた退避先実装が用意されているなら、変更を実装するべき場" +"所が２箇所になるのと、両方の実装が常に実行されることを保証するテストスイート" +"を準備するために複雑さが増加することになるので、メンテナンスがより一層困難に" +"なります。" -#: ../source/guides/supporting-multiple-python-versions.rst:42 +#: ../source/guides/packaging-binary-extensions.rst:99 msgid "" -"Performed manually, all the testing required to ensure that the package " -"works correctly on all the target Python versions (and OSs!) could be very " -"time-consuming. Fortunately, several tools are available for dealing with " -"this, and these will briefly be discussed here." +"Another disadvantage of relying on binary extensions is that alternative " +"import mechanisms (such as the ability to import modules directly from " +"zipfiles) often won't work for extension modules (as the dynamic loading " +"mechanisms on most platforms can only load libraries from disk)." msgstr "" -"パッケージが対象となる Python バージョン (および OS 群！) で正しく動作するこ" -"とを確認するために要求されるテストを全て手動でやるとなると、大変に時間がかか" -"るでしょう。幸いなことに、このようなテストを扱ういくつかのツールを利用するこ" -"とができますので、ここで簡単に議論しておきましょう。" +"バイナリ拡張に依存することによるさらなる欠点は、 (例えば zip ファイルから直接" +"にインポートする能力など) 通常とは異なるインポート機構が、しばしば拡張モ" +"ジュールでは動作しない (ほとんどのプラットフォームでは動的ロード機構はディス" +"クからライブラリを読み込むことしかできないため) ということです。" -#: ../source/guides/supporting-multiple-python-versions.rst:48 -msgid "Automated testing and continuous integration" -msgstr "自動化されたテストと継続的インテグレーション" +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "ハードコードされたアクセラレータモジュールの代わりとなるもの" -#: ../source/guides/supporting-multiple-python-versions.rst:50 +#: ../source/guides/packaging-binary-extensions.rst:108 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." +"When extension modules are just being used to make code run faster (after " +"profiling has identified the code where the speed increase is worth " +"additional maintenance effort), a number of other alternatives should also " +"be considered:" msgstr "" -"自動化されたテスト用のオンラインサービスがいくつか利用可能です。典型的には、" -"これらのサービスがあなたのソースコードリポジトリ (例えば `GitHub `_ や `Bitbucket `_) を監視していて、新しい" -"コミットが為されるたびにテストスイートを実行します。" +"拡張モジュールが単純にプログラムを速く走らせるためだけに使われてい (て、プロ" +"ファイリングの結果、メンテナンス工数が増えることを甘受しても速度を上げること" +"に価値があると判断され) る時には、他の複数の選択肢も検討しておくべきです:" -#: ../source/guides/supporting-multiple-python-versions.rst:55 +#: ../source/guides/packaging-binary-extensions.rst:113 msgid "" -"These services also offer facilities to run your project's test suite on " -"*multiple versions of Python*, giving rapid feedback about whether the code " -"will work, without the developer having to perform such tests themselves." +"look for existing optimised alternatives. The CPython standard library " +"includes a number of optimised data structures and algorithms (especially in " +"the builtins and the ``collections`` and ``itertools`` modules). The Python " +"Package Index also offers additional alternatives. Sometimes, the " +"appropriate choice of standard library or third party module can avoid the " +"need to create your own accelerator module." msgstr "" -"これらのサービスは、また、あなたのプロジェクトのテストスイートを *複数のバー" -"ジョンの Python* で走らせる機能を提供しているので、開発者がそのようなテストを" -"自分でやらなくてもソースコードが動作するか否かについて素早くフィードバックを" -"返してくれます。" +"既存の最適化された代替策を探す。CPython の標準ライブラリには、最適化された" +"データ構造やアルゴリズム (特に組み込み済みのものや ``collections`` および " +"``itertools`` モジュール) が多数含まれています。Python パッケージインデックス" +"にも他の代替となるパッケージがあります。時には、標準ライブラリや第三パーティ" +"のモジュールから適切なものを選択することで、自分自身でアクセラレータパッケー" +"ジを作成する必要に迫られないで済むでしょう。" -#: ../source/guides/supporting-multiple-python-versions.rst:59 +#: ../source/guides/packaging-binary-extensions.rst:120 msgid "" -"Wikipedia has an extensive `comparison `_ of many continuous-" -"integration systems. There are two hosted services which when used in " -"conjunction provide automated testing across Linux, Mac and Windows:" +"for long running applications, the JIT compiled `PyPy interpreter `__ may offer a suitable alternative to the standard CPython " +"runtime. The main barrier to adopting PyPy is typically reliance on other " +"binary extension modules - while PyPy does emulate the CPython C API, " +"modules that rely on that cause problems for the PyPy JIT, and the emulation " +"layer can often expose latent defects in extension modules that CPython " +"currently tolerates (frequently around reference counting errors - an object " +"having one live reference instead of two often won't break anything, but no " +"references instead of one is a major problem)." msgstr "" -"Wikipedia には、数多くの継続的インテグレーションシステムを多方面から比較した " -"`比較ページ `_ があります。その中には、両方" -"を一緒に使うことで Linux ・ Mac ・ Windows を跨いだ自動化されたテストを実行で" -"きるようなふたつのオンラインサービスもあります。" +"長時間に渡って走り続けるアプリケーションに対しては、標準の CPython ランタイム" +"の代わりに JIT コンパイルされた `PyPy インタープリタ `__ を使うことが適切な代替策となるかもしれません。 PyPy を適用しようとする" +"時、典型的には他のバイナリ拡張モジュールへの依存が主たる障害になります - " +"PyPy が CPython の C 言語 API をエミュレートする一方で、その API に依存するモ" +"ジュールの側が PyPy の JIT に問題を引き起こし、また、エミュレーション層が " +"CPython では現在は許容されているような拡張モジュール側の潜在的な瑕疵 (参照カ" +"ウントに関係するエラーであることが多い - あるオブジェクトへの参照が２個あるは" +"ずのところが１個しかないという状態は何も悪さをしませんが、１個の参照のはずが" +"参照なしとなる場合が主な問題になります) をしばしば暴露してしまうのです。" -#: ../source/guides/supporting-multiple-python-versions.rst:65 +#: ../source/guides/packaging-binary-extensions.rst:130 msgid "" -"`Travis CI `_ provides both a Linux and a macOS " -"environment. The Linux environment is Ubuntu 12.04 LTS Server Edition 64 bit " -"while the macOS is 10.9.2 at the time of writing." +"`Cython `__ is a mature static compiler that can " +"compile most Python code to C extension modules. The initial compilation " +"provides some speed increases (by bypassing the CPython interpreter layer), " +"and Cython's optional static typing features can offer additional " +"opportunities for speed increases. Using Cython still carries the " +"`disadvantages`_ associated with using binary extensions, but has the " +"benefit of having a reduced barrier to entry for Python programmers " +"(relative to other languages like C or C++)." msgstr "" -"`Travis CI `_ は Linux と macOS の両方の環境を提供しま" -"す。原稿執筆時点で、 Linux 環境は Ubuntu 12.04 LTS Server Edition 64 bit " -"で、 macOS 環境は 10.9.2 です。" +"`Cython `__ は、ほとんどの Python コードを C 言語の拡張" +"モジュールに変換できる成熟した静的コンパイラです。当初のコンパイルでは、" +"(CPython のインタプリタ層をバイパスすることによって) いくらかの速度向上が見込" +"めるとともに、 Cython のオプション扱いの静的型付け機能によってさらに速度向上" +"の機会があるかもしれません。Cython の使用には、バイナリ拡張の使用に関連した `" +"欠点`_ がまだ残っていますが、Python プログラマにとって (C 言語や C++ のような" +"他言語に比べると) 参入障壁が低いという利点があります。" -#: ../source/guides/supporting-multiple-python-versions.rst:68 +#: ../source/guides/packaging-binary-extensions.rst:139 msgid "" -"`Appveyor `_ provides a Windows environment " -"(Windows Server 2012)." +"`Numba `__ is a newer tool, created by members of " +"the scientific Python community, that aims to leverage LLVM to allow " +"selective compilation of pieces of a Python application to native machine " +"code at runtime. It requires that LLVM be available on the system where the " +"code is running, but can provide significant speed increases, especially for " +"operations that are amenable to vectorisation." msgstr "" -"`Appveyor `_ は、Windows 環境 (Windows Server " -"2012) を提供します。" +"`Numba `__ は新しめのツールで、LLVM を活用して " +"Python アプリケーションの一部分をランタイムに選択的にネイティブの機械コードに" +"コンパイルできるようにすることを目指している科学分野の Python コミュニティに" +"よって作成されました。この取り組みでは、コードが動作するシステムに LLVM が存" +"在していなければなりませんが、特にベクトル化が容易な操作について顕著な速度増" +"加を提供することができます。" -#: ../source/guides/supporting-multiple-python-versions.rst:79 +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "ハードコードされたラッパモジュールに対する代替策" + +#: ../source/guides/packaging-binary-extensions.rst:150 msgid "" -"Both `Travis CI`_ and Appveyor_ require a `YAML `_-" -"formatted file as specification for the instructions for testing. If any " -"tests fail, the output log for that specific configuration can be inspected." +"The C ABI (Application Binary Interface) is a common standard for sharing " +"functionality between multiple applications. One of the strengths of the " +"CPython C API (Application Programming Interface) is allowing Python users " +"to tap into that functionality. However, wrapping modules by hand is quite " +"tedious, so a number of other alternative approaches should be considered." msgstr "" -"`Travis CI`_ も Appveyor_ も、 `YAML `_ 形式のテスト仕様書" -"を必要とします。いずれかのテストが失敗したら、そのテスト指示設定に関するログ" -"出力を調査することができます。" +"C 言語 ABI (アプリケーションバイナリインタフェイス )は、複数のアプリケーションの間で機能を共有する上での一般的な標準で" +"す。CPython の C 言語 API (アプリケーションプログラミングインタフェイス " +") を使えば Python のユーザがその機能に入り" +"込むことができます。しかしながら、手動でモジュールごとにラッピングしていくの" +"はうんざりするような作業なので、いくつもの代替アプローチが検討されるべきで" +"す。" -#: ../source/guides/supporting-multiple-python-versions.rst:84 +#: ../source/guides/packaging-binary-extensions.rst:156 msgid "" -"For Python projects that are intended to be deployed on both Python 2 and 3 " -"with a single-source strategy, there are a number of options." +"The approaches described below don't simplify the distribution case at all, " +"but they *can* significantly reduce the maintenance burden of keeping " +"wrapper modules up to date." msgstr "" -"単一のソースコードを Python 2 と 3 の両方で稼働させる戦略を目指す Python プロ" -"ジェクトには、いくつかの方法論があります。" - -#: ../source/guides/supporting-multiple-python-versions.rst:88 -msgid "Tools for single-source Python packages" -msgstr "単一ソースコード Python パッケージのためのツール" +"以下に記述するアプローチは、単に配布物での事例ということは全くなく、むしろ" +"ラッパモジュールを最新に保つというメンテナンス上の重荷を大いに軽減することが" +"できるものです。" -#: ../source/guides/supporting-multiple-python-versions.rst:90 +#: ../source/guides/packaging-binary-extensions.rst:160 msgid "" -"`six `_ is a tool developed by Benjamin " -"Peterson for wrapping over the differences between Python 2 and Python 3. " -"The six_ package has enjoyed widespread use and may be regarded as a " -"reliable way to write a single-source Python module that can be use in both " -"Python 2 and 3. The six_ module can be used from as early as Python 2.5. A " -"tool called `modernize `_, developed by " -"Armin Ronacher, can be used to automatically apply the code modifications " -"provided by six_." +"In addition to being useful for the creation of accelerator modules, `Cython " +"`__ is also widely used for creating wrapper modules " +"for C or C++ APIs. It involves wrapping the interfaces by hand, which gives " +"a wide range of freedom in designing and optimising the wrapper code, but " +"may not be a good choice for wrapping very large APIs quickly. See the `list " +"of third-party tools `_ for " +"automatic wrapping with Cython. It also supports performance-oriented Python " +"implementations that provide a CPython-like C-API, such as PyPy and Pyston." msgstr "" -"`six `_ は、ベンジャミン・ピーターソン " -"(Benjamin Peterson) が開発した Python 2 と Python 3 の間の差異を吸収するため" -"のツールです。 six_ パッケージは広範囲に受け入れられていて、単一ソースコード" -"の Python パッケージが Python 2 と Python 3 の両方で使えるようにするための信" -"頼できる方法であるとみなされています。 six_ モジュールは早くも Python 2.5 か" -"ら使えます。アーミン・ロンチャー (Armin Ronacher) が開発した `modernize " -"`_ という名前のツールは、 six_ が提供する" -"修正を自動的にソースコードに適用するために使うことができます。" +"アクセラレータモジュールの作成に役に立つことに加えて、 `Cython `__ は C 言語や C++ の API で書かれたものをラップするモジュールを" +"作成することにも役立ちます。インターフェイスを手動でラップする作業が必要であ" +"り、それはラッパーのソースコードを設計し最適化する上では大きな自由度を与えは" +"しますが、大規模な API を素早くラップするためにはあまり良い選択ではないかもし" +"れません。Cython を用いた自動ラッピングについては `サードパーティが提供する" +"ツールのリスト `_ を見てくださ" +"い。これらは、 PyPy や Pyston のような CPython に類似した C-API を提供する性" +"能重視の Python 実装をもサポートしています。" -#: ../source/guides/supporting-multiple-python-versions.rst:99 +#: ../source/guides/packaging-binary-extensions.rst:171 msgid "" -"Similar to six_, `python-future `_ " -"is a package that provides a compatibility layer between Python 2 and Python " -"3 source code; however, unlike six_, this package aims to provide " -"interoperability between Python 2 and Python 3 with a language syntax that " -"matches one of the two Python versions: one may use" +":doc:`pybind11 ` is a pure C++11 library that provides a " +"clean C++ interface to the CPython (and PyPy) C API. It does not require a " +"pre-processing step; it is written entirely in templated C++. Helpers are " +"included for Setuptools or CMake builds. It was based on `Boost.Python " +"`__, " +"but doesn't require the Boost libraries or BJam." msgstr "" -"six_ と同様に、`python-future `_ も" -"ソースコード上で Python 2 と Python 3 の間の互換を保つ層を提供するパッケージ" -"です; しかしながら、 six_ とは異なり、このパッケージでは、ふたつの Python " -"バージョンのうちの片方の言語文法で Python 2 と Python 3 の間の相互互換性を提" -"供しようとしています: 片方しか使えません" - -#: ../source/guides/supporting-multiple-python-versions.rst:106 -msgid "a Python 2 (by syntax) module in a Python 3 project." -msgstr "Python 3 のプロジェクトにおける Python 2 (文法による) モジュール。" +":doc:`pybind11 ` は純粋な C++11 で書かれたライブラリで、綺麗" +"な C++ インタフェイスを CPython (および PyPy) の C 言語 API に提供します。事" +"前処理 (pre-processing) の段階が不要で、全体がテンプレート化された C++ で書か" +"れています。ヘルパーツールが Setuptools や CMake ビルドに含まれています。 " +"`Boost.Python `__ を基礎にしていますが、Boost ライブラリや BJam がなくてはダメと" +"いうことはありません。" -#: ../source/guides/supporting-multiple-python-versions.rst:107 -msgid "a Python 3 (by syntax) module in a *Python 2* project." +#: ../source/guides/packaging-binary-extensions.rst:178 +msgid "" +":doc:`cffi ` is a project created by some of the PyPy developers " +"to make it straightforward for developers that already know both Python and " +"C to expose their C modules to Python applications. It also makes it " +"relatively straightforward to wrap a C module based on its header files, " +"even if you don't know C yourself." msgstr "" -"*Python 2* で書かれたプロジェクトにおける、 Python 3 (文法による) モジュー" -"ル。" +":doc:`cffi ` は、 Python と C 言語の両方を知っている開発者が C 言" +"語で書いたモジュールを Python アプリケーションから単刀直入に使えるようにと何" +"人かの PyPy 開発者たちが作成しました。たとえ C 言語を知らなくても、 C 言語の" +"モジュールをそのヘッダファイルに基づいてラップすることもいくらか簡単になりま" +"した。" -#: ../source/guides/supporting-multiple-python-versions.rst:109 +#: ../source/guides/packaging-binary-extensions.rst:184 msgid "" -"Because of the bi-directionality, python-future_ offers a pathway to " -"converting a Python 2 package to Python 3 syntax module-by-module. However, " -"in contrast to six_, python-future_ is supported only from Python 2.6. " -"Similar to modernize_ for six_, python-future_ comes with two scripts called " -"``futurize`` and ``pasteurize`` that can be applied to either a Python 2 " -"module or a Python 3 module respectively." +"One of the key advantages of ``cffi`` is that it is compatible with the PyPy " +"JIT, allowing CFFI wrapper modules to participate fully in PyPy's tracing " +"JIT optimisations." msgstr "" -"双方向性の故に、 python-future_ は Python 2 で書かれたパッケージをモジュール" -"毎に Python 3 の文法に変換する通路を提供します。しかしながら、 six_ とは異な" -"り、 python-future_ は Python 2.6 からしかサポートされていません。 six_ に対" -"する modernize_ と同様に、 python-future_ は、Python 2 のモジュールに適用でき" -"る ``futurize`` と Python 3 モジュールに適用できる ``pasteurize`` と呼ばれる" -"ふたつのスクリプトを備えています。" +"``cffi`` の最も重要な利点のひとつはPyPy JIT と一緒に使えることで、CFFI ラッパ" +"モジュールが PyPy の実行中の JIT 最適化に同居できるのです。" -#: ../source/guides/supporting-multiple-python-versions.rst:116 +#: ../source/guides/packaging-binary-extensions.rst:188 msgid "" -"Use of six_ or python-future_ adds an additional runtime dependency to your " -"package: with python-future_, the ``futurize`` script can be called with the " -"``--stage1`` option to apply only the changes that Python 2.6+ already " -"provides for forward-compatibility to Python 3. Any remaining compatibility " -"problems would require manual changes." +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." msgstr "" -"six_ ないし python-future_ を使用すると、追加的な動作時依存性がパッケージに追" -"加されます: python-future_ では ``futurist`` スクリプトを ``--stage1`` オプ" -"ションとともに呼び出すことで Python 2.6 以降に既に備えられた Python 3 との前" -"方互換性を用いる修正だけを行うことができます。残りの互換性問題は、手作業で修" -"正しなければなりません。" - -#: ../source/guides/supporting-multiple-python-versions.rst:123 -msgid "What's in which Python?" -msgstr "どの Python に何がある？" +"`SWIG `__ は、 Python を含むさまざまなプログラミング言" +"語から C 言語や C++ のコードへのインタフェースを生成できるラッパインタフェー" +"ス生成ツールです。" -#: ../source/guides/supporting-multiple-python-versions.rst:125 +#: ../source/guides/packaging-binary-extensions.rst:192 msgid "" -"Ned Batchelder provides a list of changes in each Python release for `Python " -"2 `__, " -"`Python 3.0-3.3 `__ and `Python 3.4-3.6 `__. These lists may be used " -"to check whether any changes between Python versions may affect your package." +"The standard library's ``ctypes`` module, while useful for getting access to " +"C level interfaces when header information isn't available, suffers from the " +"fact that it operates solely at the C ABI level, and thus has no automatic " +"consistency checking between the interface actually being exported by the " +"library and the one declared in the Python code. By contrast, the above " +"alternatives are all able to operate at the C *API* level, using C header " +"files to ensure consistency between the interface exported by the library " +"being wrapped and the one expected by the Python wrapper module. While " +"``cffi`` *can* operate directly at the C ABI level, it suffers from the same " +"interface inconsistency problems as ``ctypes`` when it is used that way." msgstr "" -"Ned Batchelder は、Python の各リリースのそれぞれに一連の修正、つまり、 " -"`Python 2 `__、 `Python 3.0-3.3 `__、 そして `Python 3.4-3.6 `__ を加えるこ" -"とができます。これらのリストは、 Python のバージョン間の変更が特定のパッケー" -"ジに影響を与えるか否かを確認するためにも使えることでしょう。" - -#: ../source/guides/supporting-windows-using-appveyor.rst:5 -msgid "Supporting Windows using Appveyor" -msgstr "Appveyor を用いて Windows をサポートする" +"標準ライブラリの ``ctypes`` モジュールは、ヘッダの情報が得られない時でも C 言" +"語レベルのインタフェイスにアクセスできる点が役に立つ一方で、 C 言語の ABI の" +"レベルでのみ動作するため実際にエクスポートされているインタフェースと Python " +"コード側での宣言との間の一貫性を自動的に確認する仕組みがないという点が弊害を" +"引き起こすかもしれません。対照的に、上記の代替策はすべて C 言語の *API* のレ" +"ベルで動作するので、 C 言語のヘッダファイルを使ってライブラリからエクスポート" +"されラップされるインタフェイスと Python 側のラッパモジュールが期待しているイ" +"ンタフェースとの間の一貫性を保証することができます。 ``cffi`` は C 言語の " +"ABI のレベルで直接に動作する *ことができる* 一方で、そのように使った場合には " +"``ctypes`` と同じく一貫性を欠いたインタフェースの問題を孕みます。" -#: ../source/guides/supporting-windows-using-appveyor.rst:8 -msgid "2015-12-03" -msgstr "2015-12-03" +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "低レベルのシステムアクセスを行う代替策" -#: ../source/guides/supporting-windows-using-appveyor.rst:10 +#: ../source/guides/packaging-binary-extensions.rst:208 msgid "" -"This section covers how to use the free `Appveyor`_ continuous integration " -"service to provide Windows support for your project. This includes testing " -"the code on Windows, and building Windows-targeted binaries for projects " -"that use C extensions." +"For applications that need low level system access (regardless of the " +"reason), a binary extension module often *is* the best way to go about it. " +"This is particularly true for low level access to the CPython runtime " +"itself, since some operations (like releasing the Global Interpreter Lock) " +"are simply invalid when the interpreter is running code, even if a module " +"like ``ctypes`` or ``cffi`` is used to obtain access to the relevant C API " +"interfaces." msgstr "" -"この節では、無料の `Appveyor`_ 継続的インテグレーションサービスを使ってあなた" -"のプロジェクトで Windows をサポートする方法について議論します。これには、 " -"Windows におけるソースコードのテストや、 C 言語拡張を含むプロジェクトの " -"Windows 向けのバイナリへのビルドを含みます。" +"(理由を問わず) 低レベルのシステムにアクセスする必要のあるアプリケーションに" +"とって、バイナリ拡張モジュールはしばしば *進むべき最良の道* です。これは、 " +"``ctypes`` や ``cffi`` といったモジュールが適切な C 言語の API インタフェース" +"へのアクセスを取得するために使われている場合であってさえも、 (グローバルイン" +"タプリタロックの解除のような) いくつかの操作がインタプリタがコードを実行して" +"いる時には無効であるということだけを見ても、CPython ランタイム自身の低レベル" +"部分にアクセスする際によく当てはまると言えます。" -#: ../source/guides/supporting-windows-using-appveyor.rst:19 +#: ../source/guides/packaging-binary-extensions.rst:216 msgid "" -"Many projects are developed on Unix by default, and providing Windows " -"support can be a challenge, because setting up a suitable Windows test " -"environment is non-trivial, and may require buying software licenses." +"For cases where the extension module is manipulating the underlying " +"operating system or hardware (rather than the CPython runtime), it may " +"sometimes be better to just write an ordinary C library (or a library in " +"another systems programming language like C++ or Rust that can export a C " +"compatible ABI), and then use one of the wrapping techniques described above " +"to make the interface available as an importable Python module." msgstr "" -"多くのプロジェクトが当然のように Unix 上で開発されており、適切なWindows のテ" -"スト環境を準備することが簡単ではないこととソフトウェアライセンスを購入しなけ" -"ればならないであろうことから Windows へのサポートを提供することはある種のチャ" -"レンジになっています。" +"拡張モジュールが (CPythonのランタイムではなく) 下層のオペレーティングシステム" +"やハードウェアを操作しようとする場合には、単純に通常の C 言語 (または C++ や " +"Rust のような別のシステム言語で C 言語と互換性のある ABI をエクスポートできる" +"もの) でライブラリを書いて、それを上述のようなインポート可能な Python のモ" +"ジュールとしてインタフェースを構築できるラッピングテクニックを使う方が良いと" +"いう場合もあるでしょう。" -#: ../source/guides/supporting-windows-using-appveyor.rst:23 +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "バイナリ拡張を実装する" + +#: ../source/guides/packaging-binary-extensions.rst:227 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." +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." msgstr "" -"Appveyor サービスは継続的インテグレーションのサービスであり、 `GitHub`_ にホ" -"ストされたプロジェクトをテストするのによく使われよりよく知られている " -"`Travis`_ サービスによく似ています。しかし、 Travis とは異なり、 Appveyor の" -"ビルドワーカーは Windows であり、 Python の拡張モジュールをビルドするために必" -"要なコンパイラもインストール済みです。" +"CPython の :doc:`拡張と埋め込み ` のガイドには、 :" +"doc:`C 言語による独自の拡張モジュール ` を書くた" +"めの導入的な説明があります。" -#: ../source/guides/supporting-windows-using-appveyor.rst:29 +#: ../source/guides/packaging-binary-extensions.rst:231 msgid "" -"Windows users typically do not have access to a C compiler, and therefore " -"are reliant on projects that use C extensions distributing binary wheels on " -"PyPI in order for the distribution to be installable via ``python -m pip " -"install ``. By using Appveyor as a build service (even if not using it " -"for testing) it is possible for projects without a dedicated Windows " -"environment to provide Windows-targeted binaries." +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" msgstr "" -"Windows のユーザは C 言語のコンパイラを持っていないのが普通で、従って、C 言語" -"拡張を使うプロジェクトについては PyPI でバイナリ wheel を配布していなければ " -"``python -m pip install `` 経由で配布物をインスールすることができませ" -"ん。 (たとえテスト目的では利用しなかったとしても) Appveyor をビルドサービスと" -"して利用することで、専用の Windows 環境がなくても Windows 上で動作するバイナ" -"リを準備することができます。" +"FIXME: これが拡張モジュールを支援ツールなしで書きたいと *思わない* であろうと" +"いう理由のひとつであることを詳しく説明すること :)" -#: ../source/guides/supporting-windows-using-appveyor.rst:37 -msgid "Setting up" -msgstr "設定する" +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "拡張モジュールのライフサイクル" -#: ../source/guides/supporting-windows-using-appveyor.rst:39 -msgid "" -"In order to use Appveyor to build Windows wheels for your project, you must " -"have an account on the service. Instructions on setting up an account are " -"given in `the Appveyor documentation `__. " -"The free tier of account is perfectly adequate for open source projects." -msgstr "" -"Appveyor を用いてプロジェクトの Windows 向けの wheel をビルドするためには、こ" -"のサービスのアカウントを持っていなければなりません。アカウントの設定に関する" -"説明は `the Appveyor documentation `__ にあり" -"ます。オープンソースプロジェクトには無料アカウントで十分です。" +#: ../source/guides/packaging-binary-extensions.rst:238 +#: ../source/guides/packaging-binary-extensions.rst:244 +#: ../source/guides/packaging-binary-extensions.rst:250 +#: ../source/guides/packaging-binary-extensions.rst:256 +#: ../source/guides/packaging-binary-extensions.rst:376 +msgid "FIXME: This section needs to be fleshed out." +msgstr "FIXME: この節には肉付けが必要です。" -#: ../source/guides/supporting-windows-using-appveyor.rst:44 -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 "" -"Appveyor では `GitHub`_ や `BitBucket`_ との統合運用ができるので、プロジェク" -"トがこれらのうちのいずれかにホストされている限りは Appveyor から統合運用する" -"設定は簡単にできます。" +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "shared static state やサブインタプリタの影響" -#: ../source/guides/supporting-windows-using-appveyor.rst:48 -msgid "" -"Once you have set up your Appveyor account and added your project, Appveyor " -"will automatically build your project each time a commit occurs. This " -"behaviour will be familiar to users of Travis." -msgstr "" -"Appveyor のアカウントの設定とプロジェクトの追加が終われば、コミットが発生する" -"たびに Appveyor が自動的にプロジェクトをビルドするようになります。Travis の" -"ユーザはこのような動作に慣れていることでしょう。" +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "GIL の影響" -#: ../source/guides/supporting-windows-using-appveyor.rst:53 -msgid "Adding Appveyor support to your project" -msgstr "プロジェクトに Appveyor サポートを追加する" +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "メモリを割り当てる API 群" -#: ../source/guides/supporting-windows-using-appveyor.rst:55 +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "ABI の互換性" + +#: ../source/guides/packaging-binary-extensions.rst:264 msgid "" -"In order to define how Appveyor should build your project, you need to add " -"an :file:`appveyor.yml` file to your project. The full details of what can " -"be included in the file are covered in the Appveyor documentation. This " -"guide will provide the details necessary to set up wheel builds." +"The CPython C API does not guarantee ABI stability between minor releases " +"(3.2, 3.3, 3.4, etc.). This means that, typically, if you build an extension " +"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 "" -"Appveyor がプロジェクトをビルドする方法を定義するためには、 :file:`appveyor." -"yml` ファイルをプロジェクトに追加する必要があります。このファイルに書くことが" -"できる項目の完全な細部は、 Appveyor の説明文書で説明されています。このガイド" -"では、wheel のビルドに必要な部分に限って細部を説明します。" +"CPython の C 言語 API は、マイナーリリース (3.2, 3.3, 3.4 等) 間の ABI の互換" +"性を保証しません。これが意味するところは、典型的には、Python のあるバージョン" +"向けに拡張モジュールをビルドした時にマイナーバージョンまで同じ Python での動" +"作が保証されるだけであって、他のマイナーバージョンについては保証されないとい" +"うことです。" -#: ../source/guides/supporting-windows-using-appveyor.rst:60 +#: ../source/guides/packaging-binary-extensions.rst:270 msgid "" -"Appveyor includes by default all of the compiler toolchains needed to build " -"extensions for Python. For Python 2.7, 3.5+ and 32-bit versions of 3.3 and " -"3.4, the tools work out of the box. But for 64-bit versions of Python 3.3 " -"and 3.4, there is a small amount of additional configuration needed to let " -"distutils know where to find the 64-bit compilers. (From 3.5 onwards, the " -"version of Visual Studio used includes 64-bit compilers with no additional " -"setup)." +"Python 3.2 introduced the Limited API, with is a well-defined subset of " +"Python's C API. The symbols needed for the Limited API form the \"Stable " +"ABI\" which is guaranteed to be compatible across all Python 3.x versions. " +"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 "" -"Appveyor は、Python 向けの拡張モジュールをビルドするために必要なすべてのコン" -"パイラ・ツールチェーンをデフォルトで含んでいます。 Python 2.7 ・ 3.5+ 、およ" -"び 32 ビット版の 3.3 と 3.4 向けであれば、このツールはそのままで動作します。" -"しかし、 64 ビット版の 3.3 と 3.4 では、 distutils が 64 ビット版のコンパイラ" -"を検出できるように少量の追加的な設定が必要です。( 3.5 以降については、追加の" -"設定をしなくても Visual Studio の各バージョンに含まれている 64 ビット版コンパ" -"イラを使います)。" - -#: ../source/guides/supporting-windows-using-appveyor.rst:68 -msgid "appveyor.yml" -msgstr "appveyor.yml" +"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/supporting-windows-using-appveyor.rst:74 +#: ../source/guides/packaging-binary-extensions.rst:277 msgid "" -"This file can be downloaded from `here `__." +"CPython's :doc:`C API stability` page provides detailed " +"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/supporting-windows-using-appveyor.rst:76 +#: ../source/guides/packaging-binary-extensions.rst:283 +msgid "Building binary extensions" +msgstr "バイナリ拡張をビルドする" + +#: ../source/guides/packaging-binary-extensions.rst:285 +msgid "FIXME: Cover the build-backends available for building extensions." +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 msgid "" -"The :file:`appveyor.yml` file must be located in the root directory of your " -"project. It is in ``YAML`` format, and consists of a number of sections." +"If you plan to distribute your extension, you should provide :term:`wheels " +"` for all the platforms you intend to 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`." msgstr "" -":file:`appveyor.yml` ファイルは、プロジェクトのルートディレクトリに置かなけれ" -"ばなりません。このファイルは ``YAML`` フォーマットで書かれていて、数多くのセ" -"クションから構成されています。" +"あなたが自分の書いた拡張モジュールを配布するつもりがあるなら、あたながサポー" +"トしようと思うすべてのプラットフォーム向けに :term:`wheels ` を準備す" +"るべきです。通常はこれらを継続的インテグレーション (CI) システム上でビルドし" +"ます。:ref:`cibuildwheel` や :ref:`multibuild` のような CI から再配布が非常に" +"やりやすいバイナリをビルドするのを補助するツールの存在が知られています。" -#: ../source/guides/supporting-windows-using-appveyor.rst:79 +#: ../source/guides/packaging-binary-extensions.rst:296 msgid "" -"The ``environment`` section is the key to defining the Python versions for " -"which your wheels will be created. Appveyor comes with Python 2.6, 2.7, 3.3, " -"3.4 and 3.5 installed, in both 32-bit and 64-bit builds. The example file " -"builds for all of these environments except Python 2.6. Installing for " -"Python 2.6 is more complex, as it does not come with pip included. We don't " -"support 2.6 in this document (as Windows users still using Python 2 are " -"generally able to move to Python 2.7 without too much difficulty)." +"For most extensions, you will need to build wheels for all the platforms you " +"intend to support. This means that the number of wheels you need to build is " +"the product of::" msgstr "" -"``environment`` は、どのバージョンの Python 向けに wheel を生成するかを定義す" -"る鍵となるセクションです。 Appveyor には 32 ビット版と 64 ビット版の両方の " -"Python 2.6, 2.7, 3.3, 3.4, 3.5 が予めインストールされています。例示したファイ" -"ルでは、 Python 2.6 を除くこれらすべての環境向けにビルドするようになっていま" -"す。 Python 2.6 は pip を含まないので、これをインストールすることはより複雑で" -"す。このドキュメントでは、 Python 2.6 はサポートしません (Windows ユーザでま" -"だ Python 2 を使っているユーザであれば、大抵は大した困難に遭遇せずに Python " -"2.7 へ移行できるからです) 。" +"ほとんどの拡張部分向けに、すべてのサポートするつもりのあるプラットフォーム用" +"の wheel をビルドする必要があるでしょう。これが意味するところは、ビルドする必" +"要のある wheel 群の数が次のような掛け算になるだろうということです::" -#: ../source/guides/supporting-windows-using-appveyor.rst:87 +#: ../source/guides/packaging-binary-extensions.rst:302 msgid "" -"The ``install`` section uses pip to install any additional software that the " -"project may require. The only requirement for building wheels is the " -"``wheel`` project, but projects may wish to customise this code in certain " -"circumstances (for example, to install additional build packages such as " -"``Cython``, or test tools such as ``tox``)." +"Using CPython's :ref:`Stable ABI ` can help " +"significantly reduce the number of wheels you need to provide, since a " +"single wheel on a platform can be used with all Python minor versions; " +"eliminating one dimension of the matrix. It also removes the need to " +"generate new wheels for each new minor version of Python." msgstr "" -"``install`` セクションは、プロジェクトが必要とする追加的なソフトウェアを pip " -"を使ってインストールするのに使われます。 wheel をビルドするために必要なもの" -"は ``wheel`` プロジェクトだけですが、プロジェクトによっては特定の環境下ではこ" -"の項をカスタマイズしたいと思うかもしれません (例えば、 ``Cython`` のような追" -"加的なビルド用パッケージないし ``tox`` のようなテストツールをインストールする" -"ために)。" +"CPython の :ref:`Stable ABI ` を使うことで、準備する必要" +"のある wheel の数を大いに減らすことに役立つでしょう、というのは、あるプラット" +"フォーム上の単一の wheel が Python のすべてのマイナーバージョンで使える; つま" +"り、マトリクスの次元をひとつ削除することになるからです。さらに、新しいマイ" +"ナーバージョンの Python が出現するたびに新たに wheel を生成する必要もなくなり" +"ます。" -#: ../source/guides/supporting-windows-using-appveyor.rst:93 +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "Windows 向けのバイナリ拡張" + +#: ../source/guides/packaging-binary-extensions.rst:311 msgid "" -"The ``build`` section simply switches off builds - there is no build step " -"needed for Python, unlike languages like ``C#``." +"Before it is possible to build a binary extension, it is necessary to ensure " +"that you have a suitable compiler available. On Windows, Visual C is used to " +"build the official CPython interpreter, and should be used to build " +"compatible binary extensions. To set up a build environment for binary " +"extensions, install `Visual Studio Community Edition `__ - any recent version is fine." msgstr "" -"``build`` セクションでは単純にビルドのスイッチを切りましょう - ``C#`` のよう" -"な言語とは異なり、Python にはビルドする段階は不要なのです。" +"バイナリ拡張をビルドできるようになる前に、適切なコンパイラが利用できるように" +"なっていることを保証しなければなりません。Windows 上でCPython インタプリタを" +"ビルドするのに Visual C が使われていますが、互換性のあるバイナリ拡張をビルド" +"する時にも同じコンパイラを使うべきです。バイナリ拡張のためのビルド環境を構築" +"するためには、 `Visual Studio コミュニティエディション `__ をインストールしてください - 最近のバージョンな" +"らどれでも構いません。" -#: ../source/guides/supporting-windows-using-appveyor.rst:96 +#: ../source/guides/packaging-binary-extensions.rst:318 msgid "" -"The main sections that will need to be tailored to your project are " -"``test_script`` and ``after_test``." +"One caveat: if you use Visual Studio 2019 or later, your extension will " +"depend on an \"extra\" file, ``VCRUNTIME140_1.dll``, in addition to the " +"``VCRUNTIME140.dll`` that all previous versions back to 2015 depend on. This " +"will add an extra requirement to using your extension on versions of CPython " +"that do not include this extra file. To avoid this, you can add the compile-" +"time argument ``/d2FH4-``. Recent versions of Python may include this file." msgstr "" -"個々のプロジェクト向けに整える必要のある主なセクションは、 ``test_script`` " -"と ``after_test`` です。" +"注意: Visual Studio 2019 またはこれ以降のバージョンを使う場合には、あなたの拡" +"張モジュールは、2015 までのそれ以前のバージョンで依存していた ``VCRUNTIME140." +"dll`` に加えて、\"追加的な\" ファイルである ``VCRUNTIME140_1.dll`` にも依存す" +"るでしょう。この追加のファイルを同梱していないバージョンの CPython 上であなた" +"の拡張モジュールを使う場合には、要求事項が追加されることになります。コンパイ" +"ル時に引数 ``/d2FH4`` を追加しておくことで、これを避けることができます。最近" +"のバージョンの Python ならこのファイルを同梱しているかもしれません。" -#: ../source/guides/supporting-windows-using-appveyor.rst:99 +#: ../source/guides/packaging-binary-extensions.rst:326 msgid "" -"The ``test_script`` section is where you will run your project's tests. The " -"supplied file runs your test suite using ``setup.py test``. If you are only " -"interested in building wheels, and not in running your tests on Windows, you " -"can replace this section with a dummy command such as ``echo Skipped " -"Tests``. You may wish to use another test tool, such as ``nose`` or :file:" -"`py.test`. Or you may wish to use a test driver like ``tox`` - however if " -"you are using ``tox`` there are some additional configuration changes you " -"will need to consider, which are described below." +"Building for Python prior to 3.5 is discouraged, because older versions of " +"Visual Studio are no longer available from Microsoft. If you do need to " +"build for older versions, you can set ``DISTUTILS_USE_SDK=1`` and " +"``MSSdk=1`` to force a the currently activated version of MSVC to be found, " +"and you should exercise care when designing your extension not to malloc/" +"free memory across different libraries, avoid relying on changed data " +"structures, and so on. Tools for generating extension modules usually avoid " +"these things for you." msgstr "" -"``test_script`` セクションは、プロジェクトのテストを走らせる場所です。与えら" -"れたファイルを使って ``setup.py test`` を走らせることで一連のテストを行いま" -"す。wheel ファイルをビルドすることだけに興味があるのであれば、そして、 " -"Windows でテストをしないのであれば、このセクションに ``echo Skipped Tests`` " -"のようなダミーコマンドを書いておけば良いでしょう。 ``nose`` や :file:`py." -"test` のような他のテストツールを使いたい場合があるかもしれません。あるいは、 " -"``tox`` のようなテストドライバを使いたいと思うかもしれません - しかしなが" -"ら、 ``tox`` を使う場合には、後述の通り、もう少し追加の設定変更を検討する必要" -"があることでしょう。" +"Visual Studio の古いバージョンがもはや Microsoft 社から入手できないので、3.5" +"より古いバージョンの Python 向けにビルドすることは推奨されません。どうしても" +"古いバージョン向けにビルドする必要がある場合には、 ``DISTUTILS_USE_SDK=1`` お" +"よび ``MSSdk=1`` をセットすることで現在も使用可能なバージョンの MSVC が見つか" +"るようにすることと、あなたの拡張モジュールの中でライブラリを跨いでメモリを " +"malloc/free することのないように設計を見直すこと、また、修正されたデータ構造" +"に依存しないようにすることなどが必要です。拡張モジュールを生成するツール群" +"は、通常はこのようなことが起こらないようにしてくれています。" -#: ../source/guides/supporting-windows-using-appveyor.rst:108 +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "Linux 向けのバイナリ拡張" + +#: ../source/guides/packaging-binary-extensions.rst:339 msgid "" -"The ``after_test`` runs once your tests have completed, and so is where the " -"wheels should be built. Assuming your project uses the recommended tools " -"(specifically, ``setuptools``) then the ``setup.py bdist_wheel`` command " -"will build your wheels." +"Linux binaries must use a sufficiently old glibc to be compatible with older " +"distributions. The `manylinux `_ Docker " +"images provide a build environment with a glibc old enough to support most " +"current Linux distributions on common architectures." msgstr "" -"``after_test`` は、テストが完了したあとに一度だけ走り、したがって、ここで " -"wheel ファイルを生成するべきです。あなたのプロジェクトで推奨ツール (とりわけ " -"``setuptools``) を使っているなら、 ``setup.py bdist_wheel`` コマンドで wheel " -"ファイルを生成できます。" +"Linux のバイナリは、古い配布物と互換性を保つために十分に古い glibc を使わなけ" +"ればなりません。 `manylinux `_ の Docker " +"イメージを使えば、よくあるアーキテクチャのほとんどの現行版 Linux 配布物をサ" +"ポートするのに十分なほど古い glibc を伴ったビルド環境を準備できるでしょう。" -#: ../source/guides/supporting-windows-using-appveyor.rst:113 +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "macOS 向けのバイナリ拡張" + +#: ../source/guides/packaging-binary-extensions.rst:347 msgid "" -"Note that wheels will only be built if your tests succeed. If you expect " -"your tests to fail on Windows, you can skip them as described above." +"Binary compatibility on macOS is determined by the target minimum deployment " +"system, e.g. *10.9*, which is often specified with the " +"``MACOSX_DEPLOYMENT_TARGET`` environmental variable when building binaries " +"on macOS. When building with setuptools / distutils, the deployment target " +"is specified with the flag ``--plat-name``, e.g. ``macosx-10.9-x86_64``. For " +"common deployment targets for macOS Python distributions, see the `MacPython " +"Spinning Wheels wiki `_." msgstr "" -"テストが成功した場合にだけ wheel ファイルが生成されるという点に留意してくださ" -"い。 Windows ではテストが失敗するとわかっているなら、前述の通り、それを省略す" -"ることができます。" +"macOS におけるバイナリ互換性は、 macOS のバイナリをビルドする際にしばしば " +"``MACOSX_DEPLOYMENT_TARGET`` 環境変数で指定される例えば *10.9* のようなター" +"ゲットの最小デプロイメントシステムで決まります。 setuptools や distutils でビ" +"ルドする時には、デプロイメントターゲットは ``--plat-name`` フラグを使って、例" +"えば ``macosx-10.9-x86_64`` のように指定されます。 macOS 上の Python 配布物向" +"けのよくあるデプロイメントターゲットについては、 `MacPython スピンニングホ" +"イール wiki `_ を見て" +"ください。" -#: ../source/guides/supporting-windows-using-appveyor.rst:118 -msgid "Support script" -msgstr "サポートスクリプト" +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "バイナリ拡張を公開する" -#: ../source/guides/supporting-windows-using-appveyor.rst:120 +#: ../source/guides/packaging-binary-extensions.rst:359 msgid "" -"The :file:`appveyor.yml` file relies on a single support script, which sets " -"up the environment to use the SDK compiler for 64-bit builds on Python 3.3 " -"and 3.4. For projects which do not need a compiler, or which don't support " -"3.3 or 3.4 on 64-bit Windows, only the :file:`appveyor.yml` file is needed." +"Publishing binary extensions through PyPI uses the same upload mechanisms as " +"publishing pure Python packages. You build a wheel file for your extension " +"using the build-backend and upload it to PyPI using :doc:`twine `." msgstr "" -":file:`appveyor.yml` ファイルは、Python 3.3 と 3.4 上で 64 ビットでのビルドを" -"行うために SDK のコンパイラを使う環境を構築するためのひとつのサポートスクリプ" -"トに依存しています。コンパイラを必要としないプロジェクトや64 ビット版の " -"Windows 上の 3.3 や 3.4 をサポートしないプロジェクトでは、 :file:`appveyor." -"yml` ファイルさえあれば良いことになります。" +"PyPI を通じてバイナリ拡張を公開する時にも、純 Python のパッケージを公開すると" +"きと同じアップロードのメカニズムを使います。その拡張の wheel をビルドバックエ" +"ンドを使ってビルドし、 :doc:`twine ` を使って PyPI にアップロー" +"ドするということです。" -#: ../source/guides/supporting-windows-using-appveyor.rst:125 +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "バイナリだけのリリースを避ける" + +#: ../source/guides/packaging-binary-extensions.rst:367 msgid "" -"`build.cmd `__ is a Windows batch " -"script that runs a single command in an environment with the appropriate " -"compiler for the selected Python version. All you need to do is to set the " -"single environment variable ``DISTUTILS_USE_SDK`` to a value of ``1`` and " -"the script does the rest. It sets up the SDK needed for 64-bit builds of " -"Python 3.3 or 3.4, so don't set the environment variable for any other " -"builds." +"It is strongly recommended that you publish your binary extensions as well " +"as the source code that was used to build them. This allows users to build " +"the extension from source if they need to. Notably, this is required for " +"certain Linux distributions that build from source within their own build " +"systems for the distro package repositories." msgstr "" -"`build.cmd `__ は、選択されたバー" -"ジョンの Python 用の適切なコンパイラが存在する環境内で単一のコマンドを実行す" -"るような Windows のバッチスクリプトです。やらなければならないことはたった一個" -"の環境変数 ``DISTUTILS_USE_SDK`` の値を ``1`` に設定することだけで、残りはす" -"べてこのスクリプトがやってくれます。スクリプトが Python 3.3 ないし 3.4 を 64 " -"ビットでビルドするのに必要な SDK 環境を構築するので、他のビルドに使う環境変数" -"を設定してはいけません。" +"バイナリ拡張を公開する時にはそれをビルドする際に用いたソースコードも公開する" +"ことが強く推奨されています。こうすることで、必要であればユーザがその拡張を" +"ソースコードからビルドすることができます。特筆すべきことに、 Linux ディストリ" +"ビューションの中には、そのディストロ向けのパッケージリポジトリの独自のビルド" +"システム内でソースコードからビルドすることを要求するものがあるのです。" -#: ../source/guides/supporting-windows-using-appveyor.rst:132 +#: ../source/guides/packaging-binary-extensions.rst:374 +msgid "Weak linking" +msgstr "弱いリンキング " + +#: ../source/guides/packaging-binary-extensions.rst:379 +msgid "Additional resources" +msgstr "追加のリソース" + +#: ../source/guides/packaging-binary-extensions.rst:381 msgid "" -"You can simply download the batch file and include it in your project " -"unchanged." +"Cross-platform development and distribution of extension modules is a " +"complex topic, so this guide focuses primarily on providing pointers to " +"various tools that automate dealing with the underlying technical " +"challenges. The additional resources in this section are instead intended " +"for developers looking to understand more about the underlying binary " +"interfaces that those systems rely on at runtime." msgstr "" -"このバッチファイルは単純にダウンロードして修正なしにプロジェクト内に置くこと" -"ができます。" +"拡張モジュールのプラットフォームを跨ぐ開発・配布は込み入った話題なので、この" +"ガイドでは主として背景にある技術的な課題の取り扱いを自動化するさまざまなツー" +"ルへのポインタを提供することに重点を置くことにします。代わりに、この節のその" +"他の部分では、そのようなシステムが実行時に依存するような下層のバイナリインタ" +"フェースについて開発者が理解を深めるために見ることを意図しています。" -#: ../source/guides/supporting-windows-using-appveyor.rst:136 -msgid "Access to the built wheels" -msgstr "ビルドされたwheelファイルへのアクセス" +#: ../source/guides/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "sckit-build を用いたクロスプラットフォームな wheel の生成" -#: ../source/guides/supporting-windows-using-appveyor.rst:138 +#: ../source/guides/packaging-binary-extensions.rst:390 msgid "" -"When your build completes, the built wheels will be available from the " -"Appveyor control panel for your project. They can be found by going to the " -"build status page for each build in turn. At the top of the build output " -"there is a series of links, one of which is \"Artifacts\". That page will " -"include a list of links to the wheels for that Python version / " -"architecture. You can download those wheels and upload them to PyPI as part " -"of your release process." +"The `scikit-build `_ package " +"helps abstract cross-platform build operations and provides additional " +"capabilities when creating binary extension packages. Additional " +"documentation is also available on the `C runtime, compiler, and build " +"system generator `_ for Python binary extension modules." msgstr "" -"ビルドが終わると、出来上がった wheel ファイルは Appveyor のコントロールパネル" -"の当該プロジェクトのページから取り出せるでしょう。ビルドのたびに生成されるビ" -"ルド状況のページからも取り出せます。ビルド結果の出力ページの先頭には一連のリ" -"ンクがあって、そのうちの \"Artifacts\" がそれです。そのページに行くと該当する" -"バージョンの Python / アーキテクチャに応じた wheel ファイルへのリンクがあるは" -"ずです。ここから wheel ファイルをダウンロードして、あなたのリリース作業の一環" -"として PyPI へアップロードすることができるでしょう。" +"`scikit-build `_ は、抽象的な" +"ビルド作業を補助し、バイナリ拡張のパッケージを作成する時に必要な追加的な能力" +"を提供します。 Python のバイナリ拡張モジュールに関するさらなる説明文書は、 " +"`C 言語におけるランタイム・コンパイラ・ビルドシステム生成器 `_ にあります。" -#: ../source/guides/supporting-windows-using-appveyor.rst:149 -msgid "Testing with tox" -msgstr "tox を用いてテストする" +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "C/C++ による拡張モジュールの紹介" -#: ../source/guides/supporting-windows-using-appveyor.rst:151 +#: ../source/guides/packaging-binary-extensions.rst:400 msgid "" -"Many projects use the :doc:`Tox ` tool to run their tests. It " -"ensures that tests are run in an isolated environment using the exact files " -"that will be distributed by the project." +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" msgstr "" -"多くのプロジェクトで :doc:`Tox ` ツールを用いてテストを行っていま" -"す。これを使えば、プロジェクトで配布するであろうファイル群そのものを使った独" -"立した環境下でテストを実行することができます。" +"Debian システム上で CPython がどのようにして拡張モジュールを使うのかについ" +"て、もっと深掘りした説明が次の記事に出ています:" -#: ../source/guides/supporting-windows-using-appveyor.rst:155 +#: ../source/guides/packaging-binary-extensions.rst:403 msgid "" -"In order to use ``tox`` on Appveyor there are a couple of additional " -"considerations (in actual fact, these issues are not specific to Appveyor, " -"and may well affect other CI systems)." +"`What are (c)python extension modules? `_" msgstr "" -"Appveyor 上で ``tox`` を使うためには、(実際のところは、Appveyor に限ったこと" -"ではなく、他の CI システムにも影響します) いくつかの追加的な事項を検討しなけ" -"ればなりません。" +"`(c)python の拡張モジュールとはどんなものか？ `_" -#: ../source/guides/supporting-windows-using-appveyor.rst:159 -msgid "" -"By default, ``tox`` only passes a chosen subset of environment variables to " -"the test processes. Because ``distutils`` uses environment variables to " -"control the compiler, this \"test isolation\" feature will cause the tests " -"to use the wrong compiler by default." +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" msgstr "" -"デフォルトでは ``tox`` は、環境変数のうちのいくつかの選択されたサブセットだけ" -"をテストプロセスに渡します。 ``distutils`` がコンパイラを制御するのに環境変数" -"を用いるので、この \"テスト環境分離\" の機能がデフォルトではテストに誤ったコ" -"ンパイラを使ってしまう問題を引き起こすでしょう。" +"`gil をリリースする `_" -#: ../source/guides/supporting-windows-using-appveyor.rst:164 +#: ../source/guides/packaging-binary-extensions.rst:405 msgid "" -"To force ``tox`` to pass the necessary environment variables to the " -"subprocess, you need to set the ``tox`` configuration option ``passenv`` to " -"list the additional environment variables to be passed to the subprocess. " -"For the SDK compilers, you need" +"`Writing cpython extension modules using C++ `_" msgstr "" -"``tox`` がサブプロセスに必要な環境変数を渡すように強制するためには、 ``tox`` " -"の設定オプションである ``passenv`` に追加的にサブプロセスに渡すべき環境変数の" -"リストを設定する必要があります。SDK コンパイラを使うのであれば、このような設" -"定が必要です" - -#: ../source/guides/supporting-windows-using-appveyor.rst:169 -msgid "``DISTUTILS_USE_SDK``" -msgstr "``DISTUTILS_USE_SDK``" +"`C++ で cpython の拡張モジュールを書く `_" -#: ../source/guides/supporting-windows-using-appveyor.rst:170 -msgid "``MSSdk``" -msgstr "``MSSdk``" +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "名前空間パッケージをパッケージする" -#: ../source/guides/supporting-windows-using-appveyor.rst:171 -msgid "``INCLUDE``" -msgstr "``INCLUDE``" +#: ../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:" +"`distribution packages ` (referred to as " +"**distributions** in this document to avoid ambiguity). For example, if you " +"have the following package structure:" +msgstr "" +"名前空間 (Namespace) パッケージは、複数かつ個別の :term:`パッケージ ` (曖昧にならないようにこの文書では **配布物** と呼ぶことにする) を越" +"えて、単一の :term:`パッケージ ` の中のサブパッケージやモ" +"ジュールを分離できるようにすることができます。例えば、下に示すようなパッケー" +"ジ構造であれば:" -#: ../source/guides/supporting-windows-using-appveyor.rst:172 -msgid "``LIB``" -msgstr "``LIB``" +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "そして、このパッケージを自分のソースコード中で使うにはこのようにする::" -#: ../source/guides/supporting-windows-using-appveyor.rst:174 -msgid "" -"The ``passenv`` option can be set in your :file:`tox.ini`, or if you prefer " -"to avoid adding Windows-specific settings to your general project files, it " -"can be set by setting the ``TOX_TESTENV_PASSENV`` environment variable. The " -"supplied :file:`build.cmd` script does this by default whenever " -"``DISTUTILS_USE_SDK`` is set." +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -"``passenv`` オプションは、 :file:`tox.ini` ファイルでも設定可能で、あるいは、" -"Windows 特有の設定をプロジェクト全体のファイル群に追加したくなければ " -"``TOX_TESTENV_PASSENV`` 環境変数でも設定できます。 ``DISTUTILS_USE_SDK`` が設" -"定されていればいつでも、与えられた :file:`build.cmd` スクリプトがこの動作をデ" -"フォルトで実行します。" +"そうすることで、これらのサブパッケージ群を別々のふたつの配布物に分割すること" +"ができます:" -#: ../source/guides/supporting-windows-using-appveyor.rst:180 -msgid "" -"When used interactively, ``tox`` allows you to run your tests against " -"multiple environments (often, this means multiple Python versions). This " -"feature is not as useful in a CI environment like Travis or Appveyor, where " -"all tests are run in isolated environments for each configuration. As a " -"result, projects often supply an argument ``-e ENVNAME`` to ``tox`` to " -"specify which environment to use (there are default environments for most " -"versions of Python)." +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -"``tox`` を対話的に使うと、複数の環境 (これはしばしば複数のバージョンの " -"Python を意味します) でテストを実行することができます。設定ごとに独立した環境" -"ですべてのテストを実行する Travis や Appveyor のような CI 環境で見られるほど" -"には、この機能は有用ではありません。結果として、しばしばプロジェクト側から " -"``-e ENVNAME`` 引数を ``tox`` に与えてどの環境を使うべきか (ほとんどのバー" -"ジョンの Python に対応したデフォルトの環境群があります) を指定します。" +"それぞれのサブパッケージは、今や、個別にインストール・使用・バージョン管理す" +"ることができます。" -#: ../source/guides/supporting-windows-using-appveyor.rst:187 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" -"However, this does *not* work well with a Windows CI system like Appveyor, " -"where there are (for example) two installations of Python 3.4 (32-bit and 64-" -"bit) available, but only one ``py34`` environment in ``tox``." +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"from a single company). However, namespace packages come with several " +"caveats and are not appropriate in all cases. A simple alternative is to use " +"a prefix on all of your distributions such as ``import " +"mynamespace_subpackage_a`` (you could even use ``import " +"mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -"しかしながら、このやり方は、 Appveyor のような Windows 上の CI システムでは " -"(例えば) Python 3.4 の (32 版ビットと64ビット版の) ふたつの実装が利用できるの" -"に、 ``tox`` では ``py34`` 環境がひとつしかないので、うまく動きません。" +"名前空間パッケージは、 (単独の会社から出ている複数の製品向けのクライアントラ" +"イブラリの巨大な集積のような) 緩やかに関連したパッケージが多数含まれるコレク" +"ションに役立つでしょう。しかしながら、名前空間パッケージにはいくつかの注意書" +"きがあって、全ての場合に適切と言うわけではありません。単純明快な代替策は、あ" +"なたの配布物のすべてについて ``import mynamespace_subpackage_a`` のような接頭" +"語を使うことです (インポートするオブジェクトの名前を短く保つために ``import " +"mynamespace_subpackage_a as subpackage_a`` のようにインポートすることさえでき" +"ます) 。" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "名前空間パッケージを作成する" -#: ../source/guides/supporting-windows-using-appveyor.rst:191 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" -"In order to run tests using ``tox``, therefore, projects should probably use " -"the default ``py`` environment in ``tox``, which uses the Python interpreter " -"that was used to run ``tox``. This will ensure that when Appveyor runs the " -"tests, they will be run with the configured interpreter." +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" msgstr "" -"``tox`` を使ってテストを実行するためには、したがって、プロジェクトがおそらく" -"は ``tox`` のデフォルトの ``py`` 環境、ここでは ``tox`` を実行するために使わ" -"れた Python インタープリタを使うことになりますが、その環境を使うべきでしょ" -"う。" +"現在、名前空間パッケージを作るには２個の異なる手法がありますが、後者は使わな" +"い方が良いとされています:" -#: ../source/guides/supporting-windows-using-appveyor.rst:196 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" -"In order to support running under the ``py`` environment, it is possible " -"that projects with complex ``tox`` configurations might need to modify " -"their :file:`tox.ini` file. Doing so is, however, outside the scope of this " -"document." +"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 " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." msgstr "" -"``py`` 環境下での動作をサポートするためには、複雑な ``tox`` 設定を持つプロ" -"ジェクトでは :file:`tox.ini` を修正する必要があるかもしれません。そのようにす" -"ることは、しかしながら、この文書の範囲を越えます。" - -#: ../source/guides/supporting-windows-using-appveyor.rst:202 -msgid "Automatically uploading wheels" -msgstr "自動的に wheel ファイルをアップロードする" +"`組み込みの名前空間パッケージ`_ を用いる方法。この種の名前空間パッケージは :" +"pep:`420` で定義されていて、 Python 3.3 およびそれ以降で利用することができま" +"す。パッケージ中の名前空間が Python 3 だけをサポートすればよくて ``pip`` でイ" +"ンストールするのであれば、これが推奨される方法です。" -#: ../source/guides/supporting-windows-using-appveyor.rst:204 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" -"It is possible to request Appveyor to automatically upload wheels. There is " -"a ``deployment`` step available in :file:`appveyor.yml` that can be used to " -"(for example) copy the built artifacts to a FTP site, or an Amazon S3 " -"instance. Documentation on how to do this is included in the Appveyor guides." +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -"Appveyor に自動的に wheel ファイルをアップロードさせることができます。 :file:" -"`appveyor.yml` ファイルの中に ``deployment`` 段階があって、(例えば) ビルドし" -"た生成物を FTP サイトや Amazon S3 インスタンスへコピーするために使うことがで" -"きます。これをやるにはどうすれば良いかについては、 Appveyor ガイドに説明があ" -"ります。" +"`レガシー名前空間パッケージ群`_ を使ってください。これは`pkgutil 型の名前空間" +"パッケージ`_ および `pkg_resources 型の名前空間パッケージ`_ から構成されてい" +"ます。" -#: ../source/guides/supporting-windows-using-appveyor.rst:209 +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "組み込みの名前空間パッケージ" + +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" -"Alternatively, it would be possible to add a ``twine upload`` step to the " -"build. The supplied :file:`appveyor.yml` does not do this, as it is not " -"clear that uploading new wheels after every commit is desirable (although " -"some projects may wish to do this)." +"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 (following :ref:`src-layout `):" msgstr "" -"別のやり方としては、ビルドの際に ``twine upload`` 段階を追加することができる" -"でしょう。 (プロジェクトによってはそうしたいかもしれませんが) コミットのたび" -"に新しい wheel ファイルをアップロードすることが望ましいかどうかがはっきりしな" -"いので、先ほどの :file:`appveyor.yml` ファイルはこれをやりません。" - -#: ../source/guides/supporting-windows-using-appveyor.rst:215 -msgid "External dependencies" -msgstr "外部への依存関係" +"Python 3.3 では :pep:`420` から **暗黙の** 名前空間パッケージを追加しました。" +"ネイティブな名前空間パッケージを作成するのに必要なことは、名前空間パッケージ" +"のディレクトリから :file:`__init__.py` を取り除くことだけです。ファイル構造の" +"例はこちら (:ref:`ソースコードレイアウト ` に従いま" +"す):" -#: ../source/guides/supporting-windows-using-appveyor.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" -"The supplied scripts will successfully build any distribution that does not " -"rely on 3rd party external libraries for the build." +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-style :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." msgstr "" -"提供されたスクリプトを使えば、ビルド時にサードパーティの外部ライブラリに依存" -"しない配布物ならどれでもビルドに成功するでしょう。" +"名前空間パッケージを用いる各配布物で :file:`__init__.py` を省くこと、また" +"は、 pkgutil 型の :file:`__init__.py` を使用することが極めて重要です。もしい" +"ずれかの配布物でこれを忘れると、名前空間の論理が破綻して、他のサブパッケージ" +"をインポートすることができなくなります。" -#: ../source/guides/supporting-windows-using-appveyor.rst:220 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" -"It is possible to add steps to the :file:`appveyor.yml` configuration " -"(typically in the \"install\" section) to download and/or build external " -"libraries needed by the distribution. And if needed, it is possible to add " -"extra configuration for the build to supply the location of these libraries " -"to the compiler. However, this level of configuration is beyond the scope of " -"this document." +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"layout-vs-flat-layout` for more information. If however you want to manage " +"exclusions or inclusions of packages yourself, this is possible to be " +"configured in the top-level :file:`pyproject.toml`:" msgstr "" -":file:`appveyor.yml` ファイルでの設定 (典型的には \"install\" 段階) を加え" -"て、配布物に必要な外部ライブラリをダウンロードないしビルドすることは可能で" -"す。そして、もし必要なら、このようなライブラリの位置ををコンパイラに伝えるた" -"めの余分の設定を追加することもできます。しかしながら、このレベルの設定はこの" -"文書の範囲を超えます。" +"``src-layout`` ディレクトリ構造によって、ほとんどの :term:`ビルドバックエン" +"ド ` が自動的にパッケージ群を発見できるようになります。もっと" +"情報が欲しい場合は :ref:`src-layout-vs-flat-layout` を見てください。しかしな" +"がら、パッケージの包含・除外を自分自身で管理したいのであれば、トップレベル" +"の :file:`pyproject.toml` を設定することで可能です:" -#: ../source/guides/supporting-windows-using-appveyor.rst:229 -msgid "Support scripts" -msgstr "サポートスクリプト" +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "同じことが :file:`setup.cfg` で達成できます:" -#: ../source/guides/supporting-windows-using-appveyor.rst:231 -msgid "For reference, the SDK setup support script is listed here:" -msgstr "参照用に SDK を構築するサポートスクリプトをここに挙げておきます:" +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "または :file:`setup.py` ファイル:" -#: ../source/guides/supporting-windows-using-appveyor.rst:233 -msgid "``appveyor-sample/build.cmd``" -msgstr "``appveyor-sample/build.cmd``" +#: ../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/tool-recommendations.rst:5 -msgid "Tool recommendations" -msgstr "オススメのツール" +#: ../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/tool-recommendations.rst:7 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" -"The Python packaging landscape consists of many different tools. For many " -"tasks, the :term:`Python Packaging Authority ` (PyPA, the working group which encompasses many packaging tools and " -"maintains this guide) purposefully does not make a blanket recommendation; " -"for example, the reason there are many build backends is that the landscape " -"was opened up in order to enable the development of new backends serving " -"certain users' needs better than the previously unique backend, setuptools. " -"This guide does point to some tools that are widely recognized, and also " -"makes some recommendations of tools that you should *not* use because they " -"are deprecated or insecure." +"Because native and pkgutil-style namespace packages are largely compatible, " +"you can use native namespace packages in the distributions that only support " +"Python 3 and pkgutil-style namespace packages in the distributions that need " +"to support Python 2 and 3." msgstr "" -"Python パッケージングのランドスケープは、多くの異なったツール群からできていま" -"す。多くのタスクについて、 :term:`Python パッケージングオーソリティ ` (PyPA とは多数のパッケージングツール群を包含す" -"るとともにこのガイド文書を維持管理しているワーキンググループ) は、一律に適用" -"するような推奨ををしません; 例えば、数多くのビルドバックエンドが存在する理由" -"は、既存のユニークなバックエンドである setuptools よりもうまく特定のユーザの" -"ニーズに応える新しいバックエンドの開発を可能とするためにランドスケープを開放" -"しているということなのです。このガイド文書では、広く認知されている幾つかの" -"ツールを指し示していますが、また、非推奨であったり安全でなかったりするために " -"*使うべきでない* ものについても非推奨事項を記しています。" +"組み込み名前空間パッケージと pkgutil 型の名前空間パッケージは、多くの部分で互" +"換性があるので、 Python 3 しかサポートしない配布物では組み込み名前空間パッ" +"ケージを使用し、 Python 2 と Python 3 の両方をサポートしなければならない配布" +"物では pkgutil型名前空間パッケージを使うことが可能です。" -#: ../source/guides/tool-recommendations.rst:20 -msgid "Virtual environments" -msgstr "仮想環境" +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +msgstr "伝統的な名前空間パッケージ群" -#: ../source/guides/tool-recommendations.rst:22 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" -"The standard tools to create and use virtual environments manually are :ref:" -"`virtualenv` (PyPA project) and :doc:`venv ` (part of " -"the Python standard library, though missing some features of virtualenv)." +"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 "" -"仮想環境を手動で作成して使用するための標準的なツールは、 :ref:`virtualenv` " -"(PyPA project) と :doc:`venv ` (virtualenv には備わって" -"いる幾つかの機能が欠けてはいるものの、Pythonの標準ライブラリの一部) です。" - -#: ../source/guides/tool-recommendations.rst:28 -msgid "Installing packages" -msgstr "パッケージをインストールする" +"これらのふたつの方法は、 :pep:`420` 以前に名前空間を作成するのに使われました" +"が、今では過去のやり方であると考えられていて、すでにこの方法を使っているパッ" +"ケージとの互換性を必要とする場合を除いては使われるべきではないと考えられてい" +"ます。また、 :doc:`pkg_resources ` は非推奨になりま" +"した。" -#: ../source/guides/tool-recommendations.rst:30 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" -":ref:`Pip` is the standard tool to install packages from :term:`PyPI `. You may want to read pip's recommendations for :doc:" -"`secure installs `. Pip is available by default " -"in most Python installations through the standard library package :doc:" -"`ensurepip `." +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." msgstr "" -":ref:`Pip` は :term:`PyPI ` からパッケージをイン" -"ストールするための標準的なツールです。 pip の推奨事項については、 :doc:`セ" -"キュアなインストール ` を読むと良いでしょう。 " -"pip は、標準ライブラリのパッケージ :doc:`ensurepip ` を通じて、ほとんどの Python 環境でデフォルトで利用可能です。" +"既存のパッケージを移植するためには、名前空間を共有するすべてのパッケージが同" +"時に移植されなければなりません。" -#: ../source/guides/tool-recommendations.rst:36 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" -"Alternatively, consider :ref:`pipx` for the specific use case of installing " -"Python applications that are distributed through PyPI and run from the " -"command line. Pipx is a wrapper around pip and venv that installs each " -"application into a dedicated virtual environment. This avoids conflicts " -"between the dependencies of different applications, and also with system-" -"wide applications making use of the same Python interpreter (especially on " -"Linux)." +"While native namespace packages and pkgutil-style namespace packages are " +"largely compatible, pkg_resources-style namespace packages are not " +"compatible with the other methods. It's inadvisable to use different methods " +"in different distributions that provide packages to the same namespace." msgstr "" -"別のやり方としては、 PyPI を通じて配布されてコマンドラインから実行される " -"Python アプリケーションをインストールする特定のユースケースにおいては :ref:" -"`pipx` を検討してください。 pipx は pip と、専用の仮想環境の中にそれぞれのア" -"プリケーションをインストールする venv のラッパーとして動作します。これによっ" -"て、異なるアプリケーションの間の依存関係上の衝突を避け、システムワイドのアプ" -"リケーションとの間で同じ Python インタープリタを使う際の衝突を避けることがで" -"きます (特に Linux 環境で)。" +"組み込みの名前空間パッケージや pkgutil 型の名前空間パッケージは多くの点で互換" +"性がありますが、 pkg_resources 型の名前空間パッケージは他の手法とは互換性があ" +"りません。同じ名前空間向けにパッケージを提供するような複数の配布物で、異なる" +"手法を用いることは推奨されません。" + +#: ../source/guides/packaging-namespace-packages.rst:174 +msgid "pkgutil-style namespace packages" +msgstr "pkgutil 型名前空間パッケージ" + +#: ../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 " +"declare namespace packages that need to be compatible with both Python 2.3+ " +"and Python 3. This is the recommended approach for the highest level of " +"compatibility." +msgstr "" +"Python 2.3 で :doc:`pkgutil ` モジュールと :py:func:" +"`python:pkgutil.extend_path` 関数が導入されました。Python 2.3+ と Python 3 の" +"両方に互換性を持つ必要がある名前空間パッケージを宣言するのにこれが使えるかも" +"しれません。これは、互換性のレベルが最も高くなるアプローチとして推奨されてい" +"ます。" -#: ../source/guides/tool-recommendations.rst:43 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" -"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +"To create a pkgutil-style namespace package, you need to provide an :file:" +"`__init__.py` file for the namespace package:" msgstr "" -"特に科学計算ソフトウェア向けには :ref:`Conda` や :ref:`Spack` を検討してくだ" -"さい。" - -#: ../source/guides/tool-recommendations.rst:45 -msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." -msgstr "ここか、新しい議論として、\"pip vs. Conda\" の比較を書くべし。" +"pkgutil 型の名前空間パッケージを作成するには、その名前空間パッケージ用に :" +"file:`__init__.py` ファイルを準備する必要があります:" -#: ../source/guides/tool-recommendations.rst:47 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" -"Do **not** use ``easy_install`` (part of :ref:`setuptools`), which is " -"deprecated in favor of pip (see :ref:`pip vs easy_install` for details). " -"Likewise, do **not** use ``python setup.py install`` or ``python setup.py " -"develop``, which are also deprecated (see :ref:`setup-py-deprecated` for " -"background and :ref:`modernize-setup-py-project` for migration advice)." +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" msgstr "" -"``easy_install`` (:ref:`setuptools` の一部) は、 pip の登場によって非推奨に" -"なっていますので、 **使わない** でください (詳しくは :ref:`pip vs " -"easy_install` を見てください)。同様に、 ``python setup.py install`` や " -"``python setup.py develop`` も非推奨になっていますので **使わない** でくださ" -"い (背景については :ref:`setup-py-deprecated` を、移行するためのアドバイスに" -"ついては :ref:`setup.py 近代化プロジェクト ` を見" -"てください)。" +"名前空間パッケージ用の :file:`__init__.py` ファイルは、次に示すものを含んでい" +"る必要があります:" -#: ../source/guides/tool-recommendations.rst:55 -msgid "Lock files" -msgstr "ロックファイル" +#: ../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 " +"namespace logic to fail and the other sub-packages will not be importable. " +"Any additional code in :file:`__init__.py` will be inaccessible." +msgstr "" +"ある名前空間パッケージを用いる **すべての** 配布物は、 :file:`__init__.py` を" +"持っていなければなりません。もしいずれかの配布物でそうなっていなければ、名前" +"空間の論理破綻を招き、他のサブパッケージをインポートすることができなくなるで" +"しょう。 :file:`__init__.py` に他のコードを追加しても、それはアクセスできない" +"ものとなるでしょう。" -#: ../source/guides/tool-recommendations.rst:57 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" -":ref:`pip-tools` and :ref:`Pipenv` are two recognized tools to create lock " -"files, which contain the exact versions of all packages installed into an " -"environment, for reproducibility purposes." +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." msgstr "" -":ref:`pip-tools` と :ref:`Pipenv` は、再現性を高める目的でロックファイル、そ" -"こにはその環境にインストールされたパッケージの正確なバージョンを含みますが、" -"そのようなロックファイルを作成するためのツールとしてよく知られています。" +"pkgutil 型の名前空間パッケージのふたつの動作例が `pkgutil 型名前空間を例示す" +"るプロジェクト`_ にあります。" -#: ../source/guides/tool-recommendations.rst:63 -msgid "Build backends" -msgstr "ビルドバックエンド" +#: ../source/guides/packaging-namespace-packages.rst:217 +msgid "pkg_resources-style namespace packages" +msgstr "pkg_resources 型名前空間パッケージ" -#: ../source/guides/tool-recommendations.rst:67 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" -"Please, remember: this document does not seek to steer the reader towards a " -"particular tool, only to enumerate common tools. Different use cases often " -"need specialized workflows." +":doc:`Setuptools ` provides the `pkg_resources." +"declare_namespace`_ function and the ``namespace_packages`` argument to :" +"func:`~setuptools.setup`. Together these can be used to declare namespace " +"packages. While this approach is no longer recommended, it is widely present " +"in most existing namespace packages. If you are creating a new distribution " +"within an existing namespace package that uses this method then it's " +"recommended to continue using this as the different methods are not cross-" +"compatible and it's not advisable to try to migrate an existing package." msgstr "" -"どうか覚えておいてください: このドキュメントは、読者に特定のツールへ向かって" -"舵を切らせることを追求しているわけではなく、一般的なツール群を列挙しているだ" -"けです。異なるユースケースでは、しばしば、そのケースに特化したワークフローが" -"必要になります。" +":doc:`Setuptools ` は、 `pkg_resources.declare_namespace`_ " +"関数と :func:`~setuptools.setup` に渡す ``namespace_packages`` 引数を提供しま" +"す。これらを一緒に使うことで名前空間パッケージを宣言することができます。この" +"手法はもはや推奨されていませんが、既存の名前空間パッケージのほとんどで使われ" +"ています。この手法を採用している既存の名前空間パッケージの中に新しい配布物を" +"作成する時には、異なる手法が相互に互換ではないために既存パッケージを移植しよ" +"うとすることが推奨されていないので、この手法を採用し続けることを推奨します。" -#: ../source/guides/tool-recommendations.rst:71 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" -"Popular :term:`build backends ` for pure-Python packages " -"include, in alphabetical order:" +"To create a pkg_resources-style namespace package, you need to provide an :" +"file:`__init__.py` file for the namespace package:" msgstr "" -"純 Python のパッケージを取り扱う :term:`ビルドバックエンド ` " -"で人気のあるものは、アルファベット順に:" +"pkg_resources 型名前空間パッケージを作成するには、名前空間パッケージ用の :" +"file:`__init__.py` を準備する必要があります:" -#: ../source/guides/tool-recommendations.rst:74 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" -":doc:`Flit-core ` -- developed with but separate from :" -"ref:`Flit`. A minimal and opinionated build backend. It does not support " -"plugins." +"Some older recommendations advise the following in the namespace package :" +"file:`__init__.py`:" msgstr "" -":doc:`Flit-core ` -- :ref:`Flit` とともに開発されたが別" -"のもの。最小限で自己主張の強いビルドバックエンド。プラグインをサポートしな" -"い。" +"いくつかの古めの推奨では、次のような名前空間パッケージ用 :file:`__init__.py` " +"を使うように言っています:" -#: ../source/guides/tool-recommendations.rst:77 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" -"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " -"plugins." +"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 " +"advisable because pkgutil and pkg_resources-style namespace packages are not " +"cross-compatible. If the presence of setuptools is a concern then the " +"package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -"Hatchling_ -- :ref:`Hatch` とともに開発されたが別のもの。プラグインをサポート" -"する。" +"背景にあるアイデアとしては、 setuptools を使えないような稀な場合には、パッ" +"ケージを pkgutil 型パッケージに切り戻したいと言うことがあるかもしれません。 " +"pkgutil 型と pkg_resources 型の名前空間パッケージは互いに非互換なので、これは" +"推奨できるものではありません。 setuptool が存在するか否かが問題なのであれば、" +"パッケージとしては ``install_requires`` を通じて setuptools に明示的に依存す" +"ると示しておくべきです。" -#: ../source/guides/tool-recommendations.rst:79 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" -"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " -"plugins." +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -"PDM-backend_ -- :ref:`PDM` とともに開発されたが別のもの。プラグインをサポー" -"ト。" +"最後に、それぞれの配布物は :file:`setup.py` の :func:`~setuptools.setup` 向け" +"に ``namespace_packages`` 引数を準備しておく必要があります。例えば:" -#: ../source/guides/tool-recommendations.rst:81 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" -"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " -"plugins." +"A complete working example of two pkg_resources-style namespace packages can " +"be found in the `pkg_resources namespace example project`_." msgstr "" -"Poetry-core_ -- :ref:`Poetry` とともに開発されたが別のもの。プラグインをサ" -"ポート。" +"pkg_resources 型の名前空間パッケージの動作可能な二つの例が `pkg_resources 型" +"名前空間例示プロジェクト`_ で見つかるはずです。" -#: ../source/guides/tool-recommendations.rst:84 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 msgid "" -"Unlike other backends on this list, Poetry-core does not support the " -"standard :ref:`[project] table ` (it uses a " -"different format, in the ``[tool.poetry]`` table)." +"Publishing package distribution releases using GitHub Actions CI/CD workflows" msgstr "" -"このリストの他のバックエンドとは異なって、 Poetry-core は標準的な :ref:" -"`[project] table ` をサポートしていません (``[tool." -"poetry]`` テーブル内に別のフォーマットで書くことはできます)。" +"GitHub Actions CI/CD ワークフローを用いてパッケージ配布物のリリースを公開する" -#: ../source/guides/tool-recommendations.rst:88 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 msgid "" -":ref:`setuptools`, which used to be the only build backend. Supports plugins." +"`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`_ for publishing. It also uses " +"GitHub's `upload-artifact`_ and `download-artifact`_ actions for temporarily " +"storing and downloading the source packages." msgstr "" -":ref:`setuptools` は、以前は唯一のビルドバックエンドでした。プラグインをサ" -"ポート。" +"`GitHub Actions CI/CD`_ を使うと、 GitHub プラットフォームで何かイベントが発" +"生するたびに一連のコマンドを実行することができます。よくある選択のひとつは、 " +"``push`` イベントを引き金にしてあるワークフローを行うというものです。このガイ" +"ドでは、タグ付きのコミットが push されるたびに Python 配布物を公開するやり方" +"をお見せします。それには `pypa/gh-action-pypi-publish GitHub Action`_ を使っ" +"て出版 します。また、一時的な格納やソースコード配布物のダウンロード" +"のためにGitHubの `upload-artifact`_ と `download-artifact`_ を使います。" -#: ../source/guides/tool-recommendations.rst:92 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:19 msgid "" -"If you use setuptools, please be aware that some features that predate " -"standardisation efforts are now deprecated and only *temporarily kept* for " -"compatibility." +"This guide *assumes* that you already have a project that you know how to " +"build distributions for and *it lives on GitHub*. This guide also avoids " +"details of building platform specific projects. If you have binary " +"components, check out :ref:`cibuildwheel`'s GitHub Action examples." msgstr "" -"setuptools を使うのであれば、標準化の努力が為される前の幾つかの機能が今では非" -"推奨になっていて互換性を保つために *一時的に継続使用* しているだけであること" -"を忘れないでください。" +"このガイドでは、配布物をビルドするやり方を知っているプロジェクトが既にそんざ" +"いして、それが *GitHub に置いてある* ことを *前提* にしています。このガイド" +"は、また、特定のプロジェクトをビルドするプラットフォームの詳細に立ち入ること" +"はしません。もしあなたがバイナリのコンポーネントを持っているなら、 :ref:" +"`cibuildwheel` にある GitHub Action の例を調べてみてください。" -#: ../source/guides/tool-recommendations.rst:96 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:25 +msgid "Configuring trusted publishing" +msgstr "信頼された出版 を設定する" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:27 msgid "" -"In particular, do **not** use direct ``python setup.py`` invocations. On the " -"other hand, configuring setuptools with a :file:`setup.py` file is still " -"fully supported, although it is recommended to use the modern :ref:" -"`[project] table in pyproject.toml ` (or :file:" -"`setup.cfg`) whenever possible and keep :file:`setup.py` only if " -"programmatic configuration is needed. See :ref:`setup-py-deprecated`." +"This guide relies on PyPI's `trusted publishing`_ implementation to connect " +"to `GitHub Actions CI/CD`_. This is recommended for security reasons, since " +"the generated tokens are created for each of your projects individually and " +"expire automatically. Otherwise, you'll need to generate an `API token`_ for " +"both PyPI and TestPyPI. In case of publishing to third-party indexes like :" +"doc:`devpi `, you may need to provide a username/password " +"combination." msgstr "" -"とりわけ、 ``python setup.py`` のように直接に起動しては *いけません* 。他方" -"で、可能であればいつでも近代的な :ref:`[project] table in pyproject.toml " -"` (または :file:`setup.cfg`) を使うことや、プログラム" -"的な設定が必要とされる場合にのみ :file:`setup.py` を使い続けることが推奨され" -"てはいますが、 :file:`setup.py` を使って setuptools に設定を渡すことは今も完" -"全にサポートされています。 :ref:`setup-py-deprecated` を見てください。" +"このガイド文書は、`GitHub Actions CI/CD`_ に接続するために PyPI の `信頼ある" +"出版`_ の実装に依存しています。これは、生成されるトークンが各プロジェクトでそ" +"れぞれ独立に作成されて自動的に期限切れになるというセキュリティ上の理由から推" +"奨されています。さもなければ、 PyPI と TestPyPI の両方について `API トークン" +"`_ を生成する必要があるでしょう。:doc:`devpi ` のような第三者" +"パーティのインデックス向けに出版 する場合には、ユーザ名とパスワード" +"の組み合わせを提供する必要があるかもしれません。" -#: ../source/guides/tool-recommendations.rst:103 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 msgid "" -"Other examples of deprecated features you should **not** use include the " -"``setup_requires`` argument to ``setup()`` (use the :ref:`[build-system] " -"table ` in :file:`pyproject.toml` " -"instead), and the ``easy_install`` command (cf. :ref:`pip vs easy_install`)." +"Since this guide will demonstrate uploading to both PyPI and TestPyPI, we'll " +"need two trusted publishers configured. The following steps will lead you " +"through creating the \"pending\" publishers for your new :term:`PyPI project " +"`. However it is also possible to add `trusted publishing`_ to any " +"pre-existing project, if you are its owner." msgstr "" -"非推奨となった機能の他の例としては、 ``setup()`` の ``setup_requires`` 引数を" -"使うべきではなく (代わりに :file:`pyproject.toml` 内の :ref:`[build-system] " -"テーブル ` を使ってください) 、また、 " -"``easy_install`` コマンドを使うことも非推奨になっています (cf. :ref:`pip vs " -"easy_install`) 。" +"このガイドではPyPIとTestPyPIの両方へのアップロードを実証しますので、ふたつの" +"信頼あるパブリッシャが設定されていることが必要になるでしょう。以下に示すス" +"テップによって、新しい :term:`PyPI プロジェクト ` 用の \" ペンディン" +"グされた\" パブリッシャ群を作成する手順を一通りお見せします。しかしながら、あ" +"なたが所有者であるならば、任意の既存プロジェクトに `信頼ある出版`_ を追加する" +"ことが可能でもあります。" -#: ../source/guides/tool-recommendations.rst:108 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 msgid "" -"Do **not** use :ref:`distutils`, which is deprecated, and has been removed " -"from the standard library in Python 3.12, although it still remains " -"available from setuptools." +"If you followed earlier versions of this guide, you have created the secrets " +"``PYPI_API_TOKEN`` and ``TEST_PYPI_API_TOKEN`` for direct PyPI and TestPyPI " +"access. These are obsolete now and you should remove them from your GitHub " +"repository and revoke them in your PyPI and TestPyPI account settings in " +"case you are replacing your old setup with the new one." msgstr "" -":ref:`distutils` を *使わないで* ください、というのも、これは非推奨になってい" -"ますし、まだ setuptools から利用可能ではありますが Python 3.12 で標準ライブラ" -"リから取り除かれたものです。" +"このガイドの以前のバージョンを読み通したことがあるのであれば、PyPI や " +"TestPyPI への直接のアクセスをするために ``PYPI_API_TOKEN`` と " +"``TEST_PYPOI_API_TOKEN`` という秘密のトークンを作成したことでしょう。今ではこ" +"れらは過去のものとなっていて、旧来の設定を新しいものに置き換える際に GitHub " +"リポジトリから削除し、 PyPI や TestPyPI のアカウント設定から取り除くべきで" +"す。" -#: ../source/guides/tool-recommendations.rst:112 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:51 +msgid "Let's begin! 🚀" +msgstr "始めましょう! 🚀" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:53 +msgid "Go to https://pypi.org/manage/account/publishing/." +msgstr "https://pypi.org/manage/account/publishing/ へ行く。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 msgid "" -"For packages with :term:`extension modules `, it is best " -"to use a build system with dedicated support for the language the extension " -"is written in, for example:" +"Fill in the name you wish to publish your new :term:`PyPI project ` " +"under (the ``name`` value in your ``setup.cfg`` or ``pyproject.toml``), the " +"GitHub repository owner's name (org or user), and repository name, and the " +"name of the release workflow file under the ``.github/`` folder, see :ref:" +"`workflow-definition`. Finally, add the name of the GitHub Environment " +"(``pypi``) we're going set up under your repository. Register the trusted " +"publisher." msgstr "" -":term:`拡張モジュール ` を伴うパッケージについては、その拡" -"張が書かれた言語用の専用サポートのあるビルドシステムを使うのが最善です、例え" -"ば:" +"新しい :term:`PyPI プロジェクト ` 向けに発行したいと思う名前を " +"(``setup.cfg`` か ``pyproject.toml`` の中の ``名称 `` の値として)、" +"GitHub のリポジトリ所有者の名称 (org または user) と、リポジトリの名称と、 " +"``.github/`` フォルダの下のリリースワークフローの名称を記入するには、 :ref:`" +"ワークフロー定義 ` をみてください。最後に、これからリポ" +"ジトリ内に設定しようとするGutHub 環境 (``pypi``) の名称を追加してください。ト" +"ラステッドパブリッシャを登録してください。" -#: ../source/guides/tool-recommendations.rst:116 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 msgid "" -":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " -"for Go and Rust)," +"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 "" -":ref:`setuptools` -- C 言語および C++ 言語をネイティブにサポート (サードパー" -"ティのプラグインで Go 言語と Rust 言語も)、" +"ここで https://test.pypi.org/manage/account/publishing/ へ行って第２のステッ" +"プを繰り返してください、ただし、今回は GitHub 環境の名称として ``testpypi`` " +"を入力します。" -#: ../source/guides/tool-recommendations.rst:117 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 msgid "" -":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " -"by Meson," +"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 "" -":ref:`meson-python` -- C 言語・ C++ 言語・ Fortran ・ Rust およびその他の言語" -"が Meson によってサポートされています、" +"ペンディングされたパブリッシャは今やその初回使用の準備ができており、初回使用" +"を行えば自動的にあなたのプロジェクトを生成します。" -#: ../source/guides/tool-recommendations.rst:118 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 msgid "" -":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " -"by CMake," +"If you don't have a TestPyPI account, you'll need to create it. It's not the " +"same as a regular PyPI account." msgstr "" -":ref:`scikit-build-core` -- C 言語・ C++ 言語・ Fortran やその他の言語が " -"CMake によってサポートされています、" +"TestPyPI のアカウントを持っていなければ、新たに作成する必要があります。これは" +"通常の PyPI のアカウントとは別のものです。" -#: ../source/guides/tool-recommendations.rst:119 -msgid ":ref:`maturin` -- Rust, via Cargo." -msgstr ":ref:`maturin` -- Rust 、 Cargo を経由して。" +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:78 +msgid "" +"For security reasons, you must require `manual approval `_ on each run for " +"the ``pypi`` environment." +msgstr "" +"セキュリティ上の理由から、``pypi`` 環境での実行の度に、 `手動での承認 " +"`_ を要求しなければなりません。" -#: ../source/guides/tool-recommendations.rst:123 -msgid "Building distributions" -msgstr "配布物をビルドする" +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "ワークフロー定義を作成する" -#: ../source/guides/tool-recommendations.rst:125 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 msgid "" -"The standard tool to build :term:`source distributions ` and :term:`wheels ` for uploading to PyPI is :ref:" -"`build`. It will invoke whichever build backend you :ref:`declared " -"` in :file:`pyproject.toml`." +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." msgstr "" -"PyPI へアップロードするために :term:`ソースコード配布物 ` や :term:`wheels ` をビルドするための標準ツールは、 :" -"ref:`build` です。:file:`pyproject.toml` 内で `宣言された ` ビルドバックエンドが何であれ、それを起動することになりま" -"す。" +"GitHub CI/CD ワークフローは、リポジトリの ``.github/workflows/`` ディレクトリ" +"に置かれた YAML ファイルで宣言されます。" -#: ../source/guides/tool-recommendations.rst:130 -msgid "" -"Do **not** use ``python setup.py sdist`` and ``python setup.py bdist_wheel`` " -"for this task. All direct invocations of :file:`setup.py` are :ref:" -"`deprecated `." +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-test-pypi.yml`` file." msgstr "" -"この作業のために ``python setup.py sdist`` や ``python setup.py " -"bdist_wheel`` を *使わないで* ください。:file:`setup.py` を直接に起動すること" -"は :ref:`非推奨 ` になっています。" +"``.github/workflows/publish-to-test-pypi.yml`` ファイルを作成しましょう。" -#: ../source/guides/tool-recommendations.rst:134 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 msgid "" -"If you have :term:`extension modules ` and want to " -"distribute wheels for multiple platforms, use :ref:`cibuildwheel` as part of " -"your CI setup to build distributable wheels." +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" msgstr "" -"もし、 :term:`拡張モジュール ` を使っていて複数のプラット" -"フォーム向けに wheel ファイルを配布したいと考えているなら、配布可能な wheel " -"ファイルをビルドする CI 環境の一部として :ref:`cibuildwheel` を使いましょう。" +"意味のある名前で始めて、 GitHub がこのワークフローを走らせるべきイベントを定" +"義しましょう:" -#: ../source/guides/tool-recommendations.rst:140 -msgid "Uploading to PyPI" -msgstr "PyPIにアップロードする" +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:101 +msgid "Checking out the project and building distributions" +msgstr "プロジェクトをチェックアウトして配布物をビルドする" -#: ../source/guides/tool-recommendations.rst:142 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 msgid "" -"For projects hosted on GitHub, it is recommended to use the :ref:`trusted " -"publishing `, which allows the package to be securely " -"uploaded to PyPI from a GitHub Actions job. (This is not yet supported on " -"software forges other than GitHub.)" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." msgstr "" -"GitHubにホストされているプロジェクト向けには、GitHub Actions のジョブからパッ" -"ケージを安全に PyPIへアップロードすることができる :ref:`信頼ある出版 " -"` を使うことを推奨します。(これは、GitHub 以外のソフトウ" -"エア集積所ではまだサポートされていません。)" +"PyPI と TestPyPI に向けて出版 するためには、二つのジョブを定義しな" +"ければならず、また、配布物のパッケージ群をビルドするための追加のジョブも定義" +"しなければなりません。" -#: ../source/guides/tool-recommendations.rst:147 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 msgid "" -"The other available method is to upload the package manually using :ref:" -"`twine`." +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" msgstr "" -"利用可能なもうひとつの方法は、 :ref:`twine` を用いて手動でパッケージをアップ" -"ロードすることです。" +"最初に、あなたのプロジェクトの dist パッケージをビルドして、その後の使用のた" +"めに保存するジョブを定義しましょう:" -#: ../source/guides/tool-recommendations.rst:149 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 msgid "" -"**Never** use ``python setup.py upload`` for this task. In addition to " -"being :ref:`deprecated `, it is insecure." +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." msgstr "" -"このタスクを行うために ``python setup.py upload`` を使うことは *絶対にやめて" -"* ください。 :ref:`非推奨 ` であることに加えて、危険 " -" です。" - -#: ../source/guides/tool-recommendations.rst:154 -msgid "Workflow tools" -msgstr "ワークフローツール" +"これによって、あなたのリポジトリを CI ランナーにダウンロードして、利用可能な" +"最新の Python 3 リリースをインストールしアクティベートすることになります。" -#: ../source/guides/tool-recommendations.rst:156 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 msgid "" -"These tools are environment managers that automatically manage virtual " -"environments for a project. They also act as \"task runners\", allowing you " -"to define and invoke tasks such as running tests, compiling documentation, " -"regenerating some files, etc. Some of them provide shortcuts for building " -"distributions and uploading to PyPI, and some support lock files for " -"applications. They often call the tools mentioned above under the hood. In " -"alphabetical order:" +"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 "" -"これらのツール群は、プロジェクトの仮想環境を自動的に管理する環境マネージャで" -"す。これらは、テストを走らせたり、説明文書をコンパイルしたり、何らかのファイ" -"ルを再生成したり、その他のタスクを定義して起動するための \"タスク実行係\" と" -"しても動作します。これらのうちのいくつかは配布物をビルドしたり PyPI にアップ" -"ロードするためのショートカットを提供しますし、あるいは、アプリケーション向け" -"のロックファイルをサポートしています。これらは、往々にして、先述のツール群を" -"内部的に呼び出しています。アルファベット順に:" - -#: ../source/guides/tool-recommendations.rst:164 -msgid ":ref:`Flit`," -msgstr ":ref:`Flit`," - -#: ../source/guides/tool-recommendations.rst:165 -msgid ":ref:`Hatch`," -msgstr ":ref:`Hatch`," - -#: ../source/guides/tool-recommendations.rst:166 -msgid ":doc:`nox `," -msgstr ":doc:`nox `," +"そして、今や我々はソースコードから dist 配布物をビルドして保存しておくことが" +"できます。この例では、パッケージを ``build`` することになります。ですから、こ" +"れをステップリストに加えましょう:" -#: ../source/guides/tool-recommendations.rst:167 -msgid ":ref:`PDM`," -msgstr ":ref:`PDM`," +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "ワークフローのジョブ環境を定義する" -#: ../source/guides/tool-recommendations.rst:168 -msgid ":ref:`Pipenv`," -msgstr ":ref:`Pipenv`," +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:130 +msgid "" +"Now, let's add initial setup for our job that will publish to PyPI. It's a " +"process that will execute commands that we'll define later. In this guide, " +"we'll use the latest stable Ubuntu LTS version provided by GitHub Actions. " +"This also defines a GitHub Environment for the job to run in its context and " +"a URL to be displayed in GitHub's UI nicely. Additionally, it allows " +"acquiring an OpenID Connect token that the ``pypi-publish`` actions needs to " +"implement secretless trusted publishing to PyPI." +msgstr "" +"さて、PyPI へ発行 される予定のジョブに初期設定を追加しましょう。そ" +"れは、後ほど定義するであろうコマンドを実行するプロセスになるでしょう。このガ" +"イド文書では、" -#: ../source/guides/tool-recommendations.rst:169 -msgid ":ref:`Poetry`," -msgstr ":ref:`Poetry`," +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:144 +msgid "" +"This will also ensure that the PyPI publishing workflow is only triggered if " +"the current commit is tagged." +msgstr "" +"これは、当該コミットがタグ付きである時にだけ PyPI 公開 ワークフ" +"ローが起動されることをも保証するものです。" -#: ../source/guides/tool-recommendations.rst:170 -msgid ":doc:`tox `." -msgstr ":doc:`tox `." +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "PyPI へ配布物を公開する " -#: ../source/guides/using-manifest-in.rst:5 -msgid "Including files in source distributions with ``MANIFEST.in``" -msgstr "``MANIFEST.in`` を使ってソースコード配布物にファイルを含める" +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:150 +msgid "Finally, add the following steps at the end:" +msgstr "最後に、次の手続きを末尾に追加しましょう:" -#: ../source/guides/using-manifest-in.rst:7 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 msgid "" -"The information on this page has moved to :doc:`setuptools:userguide/" -"miscellaneous` in the setuptools documentation." +"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 "" -"このページの情報は、setuptools 説明文書の中の :doc:`setuptools:userguide/" -"miscellaneous` に移されました。" +"この手順では、保存されている配布パッケージが `download-artifact`_ アクション" +"によってダウンロードされた後に `pypa/gh-action-pypi-publish`_ という GitHub " +"Action: を使って、 ``dist/`` フォルダの内容物を無条件に PyPI へアップロードし" +"ます。" -#: ../source/guides/using-testpypi.rst:7 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:163 +msgid "Signing the distribution packages" +msgstr "配布パッケージに署名する" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:165 msgid "" -"``TestPyPI`` is a separate instance of the :term:`Python Package Index " -"(PyPI)` that allows you to try out the distribution tools and process " -"without worrying about affecting the real index. TestPyPI is hosted at `test." -"pypi.org `_" +"The following job signs the distribution packages with `Sigstore`_, the same " +"artifact signing system `used to sign CPython `_." msgstr "" -"``TestPyPI`` は :term:`Python パッケージインデックス ` とは別のインスタンスで、本番環境に影響を与えてしまう心配をせずに配布" -"ツールやプロセスを試してみることができます。 TestPyPI は `test.pypi.org " -"`_ にホストされています" +"以下に述べるジョブは、`CPython ` " +"に署名するのに使われる`_ ものと同じアーティファクトである `Sigstore`_ を使っ" +"て配布パッケージに署名します。" -#: ../source/guides/using-testpypi.rst:13 -msgid "Registering your account" -msgstr "アカウントを登録する" +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:168 +msgid "" +"Firstly, it uses the `sigstore/gh-action-sigstore-python GitHub Action`_ to " +"sign the distribution packages. In the next step, an empty GitHub Release " +"from the current tag is created using the ``gh`` CLI. Note this step can be " +"further customised. See the `gh release documentation `_ as a reference." +msgstr "" +"第一に、配布物パッケージに署名するのに `sigstore/gh-action-sigstore-python " +"GitHub Action`_ を使います。次の段階では、現在のタグから空の GitHub Release " +"が``hg`` CLI を使って作成されます。この段階をさらにカスタマイズすることができ" +"る点に留意してください。リファレンスとしては、`gh リリース説明文書 `_ を見てください。" -#: ../source/guides/using-testpypi.rst:15 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:176 msgid "" -"Because TestPyPI has a separate database from the live PyPI, you'll need a " -"separate user account specifically for TestPyPI. Go to https://test.pypi.org/" -"account/register/ to register your account." +"You may need to manage your ``GITHUB_TOKEN`` permissions to enable creating " +"the GitHub Release. See the `GitHub documentation `_ for " +"instructions. Specifically, the token needs the ``contents: write`` " +"permission." msgstr "" -"TestPyPI は PyPI とは別のデータベースで運用されているので、 TestPyPI 専用の" -"ユーザアカウントを作成する必要があります。 https://test.pypi.org/account/" -"register/ へ行ってアカウントを登録しましょう。" +"GitHub リリースの作成ができるような ``GITHUB_TOKEN`` パーミッションを維持する" +"必要があります。やり方については、 `GitHub 説明文書 `_ を見てくださ" +"い。具体的に言えば、トークンには ``contents: write`` 権限が必要です。" -#: ../source/guides/using-testpypi.rst:19 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:182 +msgid "Finally, the signed distributions are uploaded to the GitHub Release." +msgstr "最後に、署名された配布物が GitHub Release へアップロードされます。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:192 msgid "" -"The database for TestPyPI may be periodically pruned, so it is not unusual " -"for user accounts to be deleted." +"This is a replacement for GPG signatures, for which support has been " +"`removed from PyPI `_. " +"However, this job is not mandatory for uploading to PyPI and can be omitted." msgstr "" -"TestPyPI 用のデータベースは定期的に刈り込まれるので、往々にしてユーザアカウン" -"トが削除されることがあります。" +"これは、 `PyPI から削除された `_ GPG 署名を代替するものです。しかしながら、このジョブは PyPI " +"へアップロードする時に必須のものと言うわけではなく、省略することもできます。" -#: ../source/guides/using-testpypi.rst:24 -msgid "Using TestPyPI with Twine" -msgstr "Twine を使って TestPyPI を使う" +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "TestPyPI へ公開 するもうひとつのワークフロー" -#: ../source/guides/using-testpypi.rst:26 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 msgid "" -"You can upload your distributions to TestPyPI using :ref:`twine` by " -"specifying the ``--repository`` flag:" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" msgstr "" -":ref:`twine` に ``--repository`` フラグを指定して使うことで、配布物を " -"TestPyPI にアップロードすることができます:" +"さて、これらのステップを繰り返して、 ``jobs`` セクションに TestPyPI パッケー" +"ジインデックスに公開 するようなもうひとつのジョブを作成しましょう:" -#: ../source/guides/using-testpypi.rst:33 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:210 msgid "" -"You can see if your package has successfully uploaded by navigating to the " -"URL ``https://test.pypi.org/project/`` where " -"``sampleproject`` is the name of your project that you uploaded. It may take " -"a minute or two for your project to appear on the site." +"Requiring manual approvals in the ``testpypi`` GitHub Environment is " +"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 "" -"``https://test.pypi.org/project/`` の ``sample project`` の部" -"分をあなたがアップロードしたプロジェクトの名前に置き換えた URL を参照すれば、" -"あなたのパッケージがうまくアップロードできたかどうかを確認することができま" -"す。サイトにあなたのプロジェクトが反映されるまでには 1,2 分かかるかもしれませ" -"ん。" +"``testpypi`` Github 環境において手動の承認を要求することは、main ブランチへの" +"コミット毎に走るように設計されていることから、典型的な場合には不必要とされて" +"いて、使われるとすればリリースの公開 パイプラインが健全であることを" +"示すためであることが多いのです。" -#: ../source/guides/using-testpypi.rst:39 -msgid "Using TestPyPI with pip" -msgstr "pip で TestPyPI を使う" +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:214 +msgid "The whole CI/CD workflow" +msgstr "CI/CD ワークフローの全体像" -#: ../source/guides/using-testpypi.rst:41 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 msgid "" -"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " -"by specifying the ``--index-url`` flag:" +"This paragraph showcases the whole workflow after following the above guide." msgstr "" -":ref:`pip` で PyPI の代わりに TestPyPI からパッケージをダウンロードするに" -"は、 ``--index-url`` フラグを指定しましょう:" +"この段落には、上述のガイド文書に従った場合のワークフローの全体像を披露しま" +"す。" -#: ../source/guides/using-testpypi.rst:56 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:224 +msgid "That's all, folks!" +msgstr "これでできましたよ、皆さん!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:226 msgid "" -"If you want to allow pip to also download packages from PyPI, you can " -"specify ``--extra-index-url`` to point to PyPI. This is useful when the " -"package you're testing has dependencies:" +"Now, whenever you push a tagged commit to your Git repository remote on " +"GitHub, this workflow will publish it to PyPI. And it'll publish any push to " +"TestPyPI which is useful for providing test builds to your alpha users as " +"well as making sure that your release pipeline remains healthy!" msgstr "" -"pip が PyPI からもパッケージをダウンロードできるようにしたいのであれば、 ``--" -"extra-index-url`` に PyPI を指定しましょう。テストしようとしているパッケージ" -"が依存関係を持つ場合にこれが役に立ちます:" +"これで、手元の Git リポジトリをリモートの GitHub にタグ付きのコミットをプッ" +"シュする時はいつでも、このワークフローがそれを PyPI へ公開します。そして、" +"プッシュしさえすればいつでも TestPyPI で公開されますので、アルファ版のユーザ" +"にテストビルドを提供するためにも、あなたのリリースパイプラインが健全な状態に" +"保たれていることを確認するためにも役に立ちます!" -#: ../source/guides/using-testpypi.rst:73 -msgid "Setting up TestPyPI in :file:`.pypirc`" -msgstr ":file:`.pypirc` ファイルで TestPyPI を設定する" +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:234 +msgid "" +"If your repository has frequent commit activity and every push is uploaded " +"to TestPyPI as described, the project might exceed the `PyPI project size " +"limit `_. The limit could be " +"increased, but a better solution may constitute to use a PyPI-compatible " +"server like :ref:`pypiserver` in the CI for testing purposes." +msgstr "" +"リポジトリで活発に頻繁なコミットがあって、前述のようにあらゆるプッシュが " +"TestPyPI へアップロードされているなら、そのプロジェクトは `PyPI プロジェクト" +"サイズ制限 `_ を超過するかもしれま" +"せん。この制限を緩和することもできますが、より良い解決策は試験目的の CI の中" +"で :ref:`pypiserver` のような PyPI と互換のあるサーバを使うように構成すること" +"かもしれません。" -#: ../source/guides/using-testpypi.rst:75 +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:242 msgid "" -"If you want to avoid being prompted for your username and password every " -"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." msgstr "" -"ユーザ名やパスワードの入力を毎回促されるのを避けたいなら、 :file:`$HOME/." -"pypirc` 内で TestPyPI の設定をしておくことができます。" +"統合された GitHub Actions を最新版に保ち、頻繁にアップデートすることを推奨し" +"ます。" -#: ../source/guides/writing-pyproject-toml.rst:5 -msgid "Writing your ``pyproject.toml``" -msgstr "``pyproject.toml`` を書く" +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "ビルドすることと公開すること" -#: ../source/guides/writing-pyproject-toml.rst:7 +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "ホスティング" + +#: ../source/guides/section-install.rst:3 +msgid "Installation" +msgstr "インストール" + +#: ../source/guides/single-sourcing-package-version.rst:5 +msgid "Single-sourcing the package version" +msgstr "パッケージのバージョンを１箇所で管理する" + +#: ../source/guides/single-sourcing-package-version.rst:7 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "Todo" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "setuptools 以外のビルドバックエンドについてこのページを更新すること。" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" -"``pyproject.toml`` is a configuration file used by packaging tools, as well " -"as other tools such as linters, type checkers, etc. There are three possible " -"TOML tables in this file." +"There are many techniques to maintain a single source of truth for the " +"version number of your project:" msgstr "" -"``pyproject.toml`` は、lintersやtype checkersやその他のパッケージングツール群" -"でも同様に使われる設定ファイルです。このファイルの中には３個の TOML テーブル" -"を置くことが可能です。" +"プロジェクトのバージョン番号をたったひとつの真実の場所で管理するテクニックは" +"たくさん存在しています:" -#: ../source/guides/writing-pyproject-toml.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" -"The ``[build-system]`` table is **strongly recommended**. It allows you to " -"declare which :term:`build backend` you use and which other dependencies are " -"needed to build your project." +"Read the file in :file:`setup.py` and get the version. Example (from `pip " +"setup.py `_)::" msgstr "" -"``[build-system]`` テーブルは、 **強く推奨されています** 。これを使うことで、" -"どの :term:`ビルドバックエンド ` を使うのか、また、そのプロ" -"ジェクトをビルドするためには他のどんな依存関係が必要なのかを宣言することがで" -"きます。" +":file:`setup.py` に書かれたファイルを読み込んでバージョンを得ましょう。" +"( `pip setup.py `_ での) " +"例はこちら::" -#: ../source/guides/writing-pyproject-toml.rst:15 +#: ../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 "" +"setuptools 46.4.0 のリリースでは、代わりに次のものを :file:`setup.cfg` ファイ" +"ルに置くことで同じことを達成できています (\"package\" をパッケージをインポー" +"トする際の名前で置き換えてください) :" + +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" -"The ``[project]`` table is the format that most build backends use to " -"specify your project's basic metadata, such as the dependencies, your name, " -"etc." +"As of the release of setuptools 61.0.0, one can specify the version " +"dynamically in the project's :file:`pyproject.toml` file." msgstr "" -"``[project]`` テーブルは、依存関係や作者の名前など、そのプロジェクトの基本的" -"なメタデータを指定するためにほとんどのビルドバックエンドが用いるものです。" +"setuptools 61.0.0 のリリースの時点では、プロジェクトの :file:`pyproject." +"toml` ファイルの中にバージョンを動的に指定することができます。" -#: ../source/guides/writing-pyproject-toml.rst:18 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" -"The ``[tool]`` table has tool-specific subtables, e.g., ``[tool.hatch]``, " -"``[tool.black]``, ``[tool.mypy]``. We only touch upon this table here " -"because its contents are defined by each tool. Consult the particular tool's " -"documentation to know what it can contain." +"Please be aware that declarative config indicators, including the ``attr:`` " +"directive, are not supported in parameters to :file:`setup.py`." msgstr "" -"``[tool]`` テーブルは、例えば ``[tool.hatch]`` や ``[tool.black]`` や " -"``[tool.mypy]`` のような、ツールに特化したサブテーブルを持っています。テーブ" -"ルの内容がツール毎に定義されているので、ここでは簡単に触れるだけに留めます。" -"何を含めておくことができるのかを知るためには、それぞれのツールの説明文書に当" -"たってみてください。" +"``attr:`` ディレクティブを含む装飾的な設定指示子が、 :file:`setup.py` 向けの" +"パラメータとしてはサポートされていないことに注意してください。" -#: ../source/guides/writing-pyproject-toml.rst:25 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" -"There is a significant difference between the ``[build-system]`` and " -"``[project]`` tables. The former should always be present, regardless of " -"which build backend you use (since it *defines* the tool you use). The " -"latter is understood by *most* build backends, but some build backends use a " -"different format." +"Use an external build tool that either manages updating both locations, or " +"offers an API that both locations can use." msgstr "" -"``[build-system]`` と ``[project]`` の二つのテーブルの間には、大きな差異があ" -"ります。どんなビルドバックエンドを使うのかに関わりなく前者は常に存在していな" -"ければなりません (というのも、どのツールを使うのかをこのテーブルで定義するか" -"らです)。後者は、 *ほとんどの* ビルドバックエンドが理解しますが、一部のバック" -"エンドは異なったフォーマットのものを用います。" +"外部のビルドツールを使う場合は、両方の場所(ロケーション)を更新できるようなも" +"の、あるいは、両方のサイトから使える API を提供しているものを使いましょう。" -#: ../source/guides/writing-pyproject-toml.rst:31 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" -"At the time of writing this (November 2023), Poetry_ is a notable build " -"backend that does not use the ``[project]`` table (it uses the ``[tool." -"poetry]`` table instead)." +"Few tools you could use, in no particular order, and not necessarily " +"complete: `bump2version `_, `changes " +"`_, `commitizen `_, `zest.releaser `_." msgstr "" -"これを書いている時点 (2023年11月) では、 ``[project]`` テーブルを使わないビル" -"ドバックエンドとしては、 Poetry_ が有名です (代わりに ``[tool.poetry]`` テー" -"ブルを使います) 。" +"使えるかもしれない外部のビルドツールのリスト、ただし、順不同で、ここに挙げら" +"れていなくても使えるものがあるかもしれません: `bump2version `_, `changes `_, " +"`commitizen `_, `zest.releaser `_." -#: ../source/guides/writing-pyproject-toml.rst:35 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" -"Also, the setuptools_ build backend supports both the ``[project]`` table, " -"and the older format in ``setup.cfg`` or ``setup.py``. For new projects, it " -"is recommended to use the ``[project]`` table, and keep ``setup.py`` only if " -"some programmatic configuration is needed (such as building C extensions), " -"but the ``setup.cfg`` and ``setup.py`` formats are still valid. See :ref:" -"`setup-py-deprecated`." +"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 "" -"また、setuptools_ のビルドバックエンドは、 ``[project]`` テーブルと ``setup." -"cfg`` ないし ``setup.py`` の中のより古い形の両方をサポートしています。新しく" -"始めるプロジェクトでは ``[project]`` テーブルを使用し、 (C 言語拡張をビルドす" -"る場合のような) 何かプログラム面での設定が必要とされる場合に限って ``setup." -"py`` を使い続けることが推奨されていますが、依然として ``setup.cfg`` と " -"``setup.py`` の形式は正当なものです。 :ref:`setup-py-deprecated` をご覧くださ" -"い。" - -#: ../source/guides/writing-pyproject-toml.rst:46 -msgid "Declaring the build backend" -msgstr "ビルドバックエンドを宣言する" +"プロジェクト内にグローバル変数の ``__version__`` に値を設定した専用のモジュー" +"ル (例えば :file:`version.py`) を作って :file:`setup.py` からそれを読み取っ" +"て ``exec`` で値を変数に取り込むと良いでしょう。" -#: ../source/guides/writing-pyproject-toml.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" -"The ``[build-system]`` table contains a ``build-backend`` key, which " -"specifies the build backend to be used. It also contains a ``requires`` key, " -"which is a list of dependencies needed to build the project -- this is " -"typically just the build backend package, but it may also contain additional " -"dependencies. You can also constrain the versions, e.g., ``requires = " -"[\"setuptools >= 61.0\"]``." +"Example using this technique: `warehouse `_." msgstr "" -"``[build-system]`` テーブルは、使用されるべきビルドバックエンドを指定する " -"``build-backend`` キーを含んでいます。また、 プロジェクトをビルドするのに必要" -"な依存関係のリストである ``requires`` キーも含んでいます -- これは典型的には" -"ビルドバクエンドのパッケージだけですが、追加の依存関係を含んでいてもかまいま" -"せん。さらに、例えば ``requires = [\"setuptools >= 61.0\"]`` のようにバージョ" -"ンを制限することもできます。" +"このテクニックを使っている例: `warehouse `_ 。" -#: ../source/guides/writing-pyproject-toml.rst:54 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" -"Usually, you'll just copy what your build backend's documentation suggests " -"(after :ref:`choosing your build backend `). Here " -"are the values for some common build backends:" +"Place the value in a simple ``VERSION`` text file and have both :file:`setup." +"py` and the project code read it." msgstr "" -"通常は、ビルドバックエンドの説明文書が (:ref:`ビルドバックエンドを選択する " -"`) 示唆するものをコピーするだけでしょう。よく知られた" -"バックエンドでの値をいくつか挙げておきます:" - -#: ../source/guides/writing-pyproject-toml.rst:93 -msgid "Static vs. dynamic metadata" -msgstr "静的なメタデータと動的なメタデータ" - -#: ../source/guides/writing-pyproject-toml.rst:95 -msgid "The rest of this guide is devoted to the ``[project]`` table." -msgstr "このガイド文書の残りの部分は、``[project]`` テーブルに捧げます。" +"単純に ``VERSION`` という名前のテキストファイルに値を書いておいて、 :file:" +"`setup.py` とプロジェクトのソースコードの両方から読み込みます。" -#: ../source/guides/writing-pyproject-toml.rst:97 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" -"Most of the time, you will directly write the value of a ``[project]`` " -"field. For example: ``requires-python = \">= 3.8\"``, or ``version = " -"\"1.0\"``." +"An advantage with this technique is that it's not specific to Python. Any " +"tool can read the version." msgstr "" -"ほとんどの場合、 ``[project]`` フィールドに直接に値を書き込むことになるでしょ" -"う。例えば: ``requires-python = \">= 3.8\"`` や ``version = \"1.0\"`` などで" -"す。" +"このテクニックを使う利点は、Python に限定されたやり方ではないということです。" +"どんなツールでもバージョン番号を読み取ることができます。" -#: ../source/guides/writing-pyproject-toml.rst:101 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" -"However, in some cases, it is useful to let your build backend compute the " -"metadata for you. For example: many build backends can read the version from " -"a ``__version__`` attribute in your code, a Git tag, or similar. In such " -"cases, you should mark the field as dynamic using, e.g.," +"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 "" -"しかしながら、ビルドバックエンドにメタデータを計算させる方が役に立つ場合もあ" -"ります。例えば: 多くのビルドバックエンドがソースコードや Git タグやその他似た" -"ようなものの中にある ``__version__`` 要素を読み取ることができます。そのような" -"場合には、以下の例のような方法を使ってそのフィールドを動的なものにしておくべ" -"きです、" +"このやり方を採用するなら、 ``VERSION`` ファイルがすべてのソースコードとバイナ" +"リの配布物に含まれているように気を付けてください (例えば :file:`MANIFEST.in` " +"に ``include VERSION`` を追加しておくなど)。" -#: ../source/guides/writing-pyproject-toml.rst:112 +#: ../source/guides/single-sourcing-package-version.rst:105 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." +"Set the value in :file:`setup.py`, and have the project code use the " +"``importlib.metadata`` API to fetch the value at runtime. (``importlib." +"metadata`` was introduced in Python 3.8 and is available to older versions " +"as the ``importlib-metadata`` project.) An installed project's version can " +"be fetched with the API as follows::" msgstr "" -"フィールドが動的となっている場合、そこを埋めるのはビルドバックエンドの責任で" -"す。どうすれば良いのかについては、ビルドバックエンドの説明文書に当たってみて" -"ください。" - -#: ../source/guides/writing-pyproject-toml.rst:118 -msgid "Basic information" -msgstr "基本的な情報" - -#: ../source/guides/writing-pyproject-toml.rst:123 -#: ../source/specifications/pyproject-toml.rst:120 -#: ../source/specifications/pyproject-toml.rst:142 -#: ../source/specifications/pyproject-toml.rst:152 -msgid "``name``" -msgstr "``名称``" +":file:`setup.py` に値を保存して、プロジェクトのソースコードが ``importlib." +"metadata`` API を使ってその値を動作中に取得するようにしましょう。 " +"(``importlib.metadata`` は Python 3.8 で導入されていて、それより古いバージョ" +"ンでは ``importlib-metadata`` プロジェクトとして利用可能になっています) イン" +"ストール済みのプロジェクトのバージョン番号をこの API で取り込むには次のように" +"します::" -#: ../source/guides/writing-pyproject-toml.rst:125 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" -"Put the name of your project on PyPI. This field is required and is the only " -"field that cannot be marked as dynamic." +"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 "" -"PyPI 上でのプロジェクト名称を書いてください。このフィールドは必須のもので、動" -"的であるとマークできない唯一のフィールドです。" +"``importlib.metadata`` API が知っているのはインストールされたパッケージのメタ" +"データだけであって、現在インポートされているソースコードについて知っていると" +"は限らないことに注意してください。" -#: ../source/guides/writing-pyproject-toml.rst:133 +#: ../source/guides/single-sourcing-package-version.rst:124 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." +"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 "" -"プロジェクトの名称は、ASCII文字・数字・アンダースコア \"``_``\"・ハイフン " -"\"``-``\"・ピリオド \"``.``\" だけでできていなければなりません。また、アン" -"ダースコア・ハイフン・ピリオドで始まってはなりません。" +"あるプロジェクトで動作中にバージョン番号を取得する方法を使っているのであれ" +"ば、Python 3.8 よりも古いバージョンを使う場合はそのプロジェクトの " +"``install_requires`` に ``importlib-metadata`` を書いておかなければなりませ" +"ん::" -#: ../source/guides/writing-pyproject-toml.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 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``." +"An older (and less efficient) alternative to ``importlib.metadata`` is the " +"``pkg_resources`` API provided by ``setuptools``::" msgstr "" -"プロジェクト名の比較では、大文字小文字を区別せず、また、アンダースコア・ハイ" -"フン・ピリオドは何文字連続していても同じものとして扱います。例えば、あなたが " -"``cool-stuff`` という名前のプロジェクトを登録したなら、利用者がダウンロードし" -"たり依存関係を宣言したりするのに、次に挙げる綴りのいずれであっても使うことが" -"できます: ``Cool-Stuff`` ・ ``cool.stuff`` ・ ``COOL_STUFF`` ・ ``CoOl__-.-" -"__sTuFF`` 。" +"``importlib.metadata`` に対するもっと古い (かつ、より非効率な) 代替策は、 " +"``setuptools`` が提供する ``pkg_resources`` API です::" -#: ../source/guides/writing-pyproject-toml.rst:145 -#: ../source/specifications/pyproject-toml.rst:125 -#: ../source/specifications/pyproject-toml.rst:148 -#: ../source/specifications/pyproject-toml.rst:164 -msgid "``version``" +#: ../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 "" +"あるプロジェクトで自分自身のバージョン番号を動作中に取得するために " +"``pkg_resources`` を使っているなら、プロジェクトの ``install_requires`` のリ" +"ストには必ず ``setuptools`` が入っていないといけません。" -#: ../source/guides/writing-pyproject-toml.rst:147 -msgid "Put the version of your project." -msgstr "プロジェクトのバージョンを書いてください。" - -#: ../source/guides/writing-pyproject-toml.rst:154 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" -"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " -"release) are possible; see the :ref:`specification ` for " -"full details." +"Example using this technique: `setuptools `_." msgstr "" -"(アルファ版のリリース用の) ``2020.0.0a1`` のようなもっと込み入ったバージョン" -"指定子も可能ですので、 詳細については :ref:`仕様 ` を見て" -"ください。" +"このテクニックを使っている例: `setuptools `_." -#: ../source/guides/writing-pyproject-toml.rst:158 -msgid "This field is required, although it is often marked as dynamic using" +#: ../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 "" -"動的であるとマークされることがしばしばではありますが、このフィールドは必須の" -"ものです" +"``sample/__init__.py`` で ``__version__`` に値を設定して、 :file:`setup.py` " +"から ``sample`` をインポートしましょう。" -#: ../source/guides/writing-pyproject-toml.rst:165 +#: ../source/guides/single-sourcing-package-version.rst:165 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." +"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 "" -"これによって、 ``__version__`` 要素や Git のタグからバージョンを取得するよう" -"な使い方が可能になります。 :ref:`バージョンを１箇所で管理する ` を見てみてください。" - -#: ../source/guides/writing-pyproject-toml.rst:171 -msgid "Dependencies and requirements" -msgstr "依存関係と要求事項" - -#: ../source/guides/writing-pyproject-toml.rst:174 -#: ../source/specifications/pyproject-toml.rst:354 -msgid "``dependencies``/``optional-dependencies``" -msgstr "``dependencies``/``optional-dependencies``" - -#: ../source/guides/writing-pyproject-toml.rst:176 -msgid "If your project has dependencies, list them like this:" -msgstr "もしプロジェクトに依存関係があるなら、このように列挙してください:" +"このテクニックはよく知られたものだが、 ``install_requires`` で定義された依存" +"先パッケージを ``sample/__init__.py`` がインポートしている場合には、そのよう" +"なパッケージは :file:`setup.py` が実行される時点ではまだインストールされてい" +"ない可能性が高いので、失敗するであろうということに注意してください。" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" -"See :ref:`Dependency specifiers ` for the full syntax " -"you can use to constrain versions." +"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 " +"there using `setuptools_scm `_." msgstr "" -"バージョンに制限をかけるために使えるあらゆるシンタックスについては、 :ref:`依" -"存関係指定子 ` を参照してください。" +"ソースコード内ではなくバージョンコントロールシステム (Git, Mercurialなど) の" +"タグの中にバージョン番号を保持して、そこから `setuptools_scm `_ を使って取り出しましょう。" -#: ../source/guides/writing-pyproject-toml.rst:191 +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "複数の Python バージョンをサポートする" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "2014-12-24" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 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``." +"In addition to the work required to create a Python package, it is often " +"necessary that the package must be made available on different versions of " +"Python. Different Python versions may contain different (or renamed) " +"standard library packages, and the changes between Python versions 2.x and 3." +"x include changes in the language syntax." msgstr "" -"パッケージの特定の機能にのみ必要なものであれば、依存関係のうちのいくつかをオ" -"プションにしたい時があるかもしれません。そのような場合には、 ``optional-" -"dependencies`` に置きましょう。" +"Python パッケージを作成するのに必要とされる仕事に加えて、しばしばそのパッケー" +"ジが異なるバージョンの Python に対応することが求められます。 Python のバー" +"ジョンが異なると、異なる (または名称を変更した) 標準ライブラリパッケージを含" +"むことがあり、 Python 2.x と 3.x の間には言語の文法に違いがあります。" -#: ../source/guides/writing-pyproject-toml.rst:204 +#: ../source/guides/supporting-multiple-python-versions.rst:42 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." +"Performed manually, all the testing required to ensure that the package " +"works correctly on all the target Python versions (and OSs!) could be very " +"time-consuming. Fortunately, several tools are available for dealing with " +"this, and these will briefly be discussed here." msgstr "" -"キーのぞれぞれが \"余分のパッケージング \" を定義します。上" -"の例では、プロジェクトを例えば GUI サポート付きでインストールするためには " -"``pip install your-project-name[gui]`` を使うことができます。" +"パッケージが対象となる Python バージョン (および OS 群！) で正しく動作するこ" +"とを確認するために要求されるテストを全て手動でやるとなると、大変に時間がかか" +"るでしょう。幸いなことに、このようなテストを扱ういくつかのツールを利用するこ" +"とができますので、ここで簡単に議論しておきましょう。" -#: ../source/guides/writing-pyproject-toml.rst:213 -#: ../source/specifications/pyproject-toml.rst:145 -#: ../source/specifications/pyproject-toml.rst:226 -msgid "``requires-python``" -msgstr "``requires-python``" +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "自動化されたテストと継続的インテグレーション" -#: ../source/guides/writing-pyproject-toml.rst:215 +#: ../source/guides/supporting-multiple-python-versions.rst:50 msgid "" -"This lets you declare the minimum version of Python that you support " -"[#requires-python-upper-bounds]_." +"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." msgstr "" -"これによってサポートされている Python の上限のバージョンを宣言することができ" -"ます [#requires-python-upper-bounds]_ 。" - -#: ../source/guides/writing-pyproject-toml.rst:227 -msgid "Creating executable scripts" -msgstr "実行可能なスクリプトを作成する" +"自動化されたテスト用のオンラインサービスがいくつか利用可能です。典型的には、" +"これらのサービスがあなたのソースコードリポジトリ (例えば `GitHub `_ や `Bitbucket `_) を監視していて、新しい" +"コミットが為されるたびにテストスイートを実行します。" -#: ../source/guides/writing-pyproject-toml.rst:229 +#: ../source/guides/supporting-multiple-python-versions.rst:55 msgid "" -"To install a command as part of your package, declare it in the ``[project." -"scripts]`` table." +"These services also offer facilities to run your project's test suite on " +"*multiple versions of Python*, giving rapid feedback about whether the code " +"will work, without the developer having to perform such tests themselves." msgstr "" -"パッケージの一部としてコマンドをインストールするためには、 ``[project." -"scripts]`` テーブルで宣言してください。" +"これらのサービスは、また、あなたのプロジェクトのテストスイートを *複数のバー" +"ジョンの Python* で走らせる機能を提供しているので、開発者がそのようなテストを" +"自分でやらなくてもソースコードが動作するか否かについて素早くフィードバックを" +"返してくれます。" -#: ../source/guides/writing-pyproject-toml.rst:237 +#: ../source/guides/supporting-multiple-python-versions.rst:59 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()``." +"Wikipedia has an extensive `comparison `_ of many continuous-" +"integration systems. There are two hosted services which when used in " +"conjunction provide automated testing across Linux, Mac and Windows:" msgstr "" -"この例では、プロジェクトをインストールした後に ``spam-cli`` コマンドが利用で" -"きるようになるでしょう。このコマンドを実行することで、 ``from spam import " -"main_cli; main_cli()`` と同等のことを行うでしょう。" +"Wikipedia には、数多くの継続的インテグレーションシステムを多方面から比較した " +"`比較ページ `_ があります。その中には、両方" +"を一緒に使うことで Linux ・ Mac ・ Windows を跨いだ自動化されたテストを実行で" +"きるようなふたつのオンラインサービスもあります。" -#: ../source/guides/writing-pyproject-toml.rst:241 +#: ../source/guides/supporting-multiple-python-versions.rst:65 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]``." +"`Travis CI `_ provides both a Linux and a macOS " +"environment. The Linux environment is Ubuntu 12.04 LTS Server Edition 64 bit " +"while the macOS is 10.9.2 at the time of writing." msgstr "" -"Windows では、このやり方でパッケージされたスクリプト群はターミナルを必要とし" -"ますので、グラフィカルなアプリケーションの内部から起動した場合にはターミナル" -"がポップアップすることでしょう。これが起きないようにするためには、 " -"``[project.scripts]`` の代わりに ``[project.gui-scripts]`` テープルを使ってく" -"ださい。" +"`Travis CI `_ は Linux と macOS の両方の環境を提供しま" +"す。原稿執筆時点で、 Linux 環境は Ubuntu 12.04 LTS Server Edition 64 bit " +"で、 macOS 環境は 10.9.2 です。" -#: ../source/guides/writing-pyproject-toml.rst:251 +#: ../source/guides/supporting-multiple-python-versions.rst:68 msgid "" -"In that case, launching your script from the command line will give back " -"control immediately, leaving the script to run in the background." +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." msgstr "" -"そうすることで、コマンドラインからスクリプトを起動してスクリプトがバックグラ" -"ウンドで走らせることですぐに制御を取り戻すことができるでしょう。" +"`Appveyor `_ は、Windows 環境 (Windows Server " +"2012) を提供します。" -#: ../source/guides/writing-pyproject-toml.rst:254 +#: ../source/guides/supporting-multiple-python-versions.rst:79 msgid "" -"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " -"is only relevant on Windows." +"Both `Travis CI`_ and Appveyor_ require a `YAML `_-" +"formatted file as specification for the instructions for testing. If any " +"tests fail, the output log for that specific configuration can be inspected." msgstr "" -"Windows 上では、 ``[project.scripts]`` と ``[project.gui-scripts]`` の間の差" -"異だけが実質的に効果を持ちます。" - -#: ../source/guides/writing-pyproject-toml.rst:260 -msgid "About your project" -msgstr "あなたのプロジェクトについて" - -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/pyproject-toml.rst:251 -msgid "``authors``/``maintainers``" -msgstr "``authors``/``maintainers``" +"`Travis CI`_ も Appveyor_ も、 `YAML `_ 形式のテスト仕様書" +"を必要とします。いずれかのテストが失敗したら、そのテスト指示設定に関するログ" +"出力を調査することができます。" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/supporting-multiple-python-versions.rst:84 msgid "" -"Both of these fields contain lists of people identified by a name and/or an " -"email address." +"For Python projects that are intended to be deployed on both Python 2 and 3 " +"with a single-source strategy, there are a number of options." msgstr "" -"これらのフィールドは両方とも名前とメールアドレスの両方またはいずれかで識別さ" -"れる人々のリストを含みます。" +"単一のソースコードを Python 2 と 3 の両方で稼働させる戦略を目指す Python プロ" +"ジェクトには、いくつかの方法論があります。" -#: ../source/guides/writing-pyproject-toml.rst:285 -#: ../source/specifications/pyproject-toml.rst:135 -#: ../source/specifications/pyproject-toml.rst:177 -msgid "``description``" -msgstr "``説明 ``" +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "単一ソースコード Python パッケージのためのツール" -#: ../source/guides/writing-pyproject-toml.rst:287 +#: ../source/guides/supporting-multiple-python-versions.rst:90 msgid "" -"This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_), and " -"other places such as lists of search results (`example `_)." +"`six `_ is a tool developed by Benjamin " +"Peterson for wrapping over the differences between Python 2 and Python 3. " +"The six_ package has enjoyed widespread use and may be regarded as a " +"reliable way to write a single-source Python module that can be use in both " +"Python 2 and 3. The six_ module can be used from as early as Python 2.5. A " +"tool called `modernize `_, developed by " +"Armin Ronacher, can be used to automatically apply the code modifications " +"provided by six_." msgstr "" -"これは、PyPI におけるプロジェクトページの \"ヘッドライン\" (`例 `_) や検索結果 (`例 `_) のような他の場所で表示されるも" -"のなので、１行でプロジェクトの説明をしたものであるべきです。" - -#: ../source/guides/writing-pyproject-toml.rst:298 -#: ../source/specifications/pyproject-toml.rst:144 -#: ../source/specifications/pyproject-toml.rst:187 -msgid "``readme``" -msgstr "``readme``" +"`six `_ は、ベンジャミン・ピーターソン " +"(Benjamin Peterson) が開発した Python 2 と Python 3 の間の差異を吸収するため" +"のツールです。 six_ パッケージは広範囲に受け入れられていて、単一ソースコード" +"の Python パッケージが Python 2 と Python 3 の両方で使えるようにするための信" +"頼できる方法であるとみなされています。 six_ モジュールは早くも Python 2.5 か" +"ら使えます。アーミン・ロンチャー (Armin Ronacher) が開発した `modernize " +"`_ という名前のツールは、 six_ が提供する" +"修正を自動的にソースコードに適用するために使うことができます。" -#: ../source/guides/writing-pyproject-toml.rst:300 +#: ../source/guides/supporting-multiple-python-versions.rst:99 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." +"Similar to six_, `python-future `_ " +"is a package that provides a compatibility layer between Python 2 and Python " +"3 source code; however, unlike six_, this package aims to provide " +"interoperability between Python 2 and Python 3 with a language syntax that " +"matches one of the two Python versions: one may use" msgstr "" -"これはプロジェクトの長めの説明文で、PyPI のプロジェクトページに表示されます。" -"典型的には、プロジェクトには ``README.md`` か ``README.rst`` のファイルが存在" -"するものなので、その場合にはここにはそのファイル名だけを書いておけば良いで" -"しょう。" +"six_ と同様に、`python-future `_ も" +"ソースコード上で Python 2 と Python 3 の間の互換を保つ層を提供するパッケージ" +"です; しかしながら、 six_ とは異なり、このパッケージでは、ふたつの Python " +"バージョンのうちの片方の言語文法で Python 2 と Python 3 の間の相互互換性を提" +"供しようとしています: 片方しか使えません" -#: ../source/guides/writing-pyproject-toml.rst:309 -msgid "The README's format is auto-detected from the extension:" -msgstr "README のフォーマットは拡張から自動的に検出されます:" +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "Python 3 のプロジェクトにおける Python 2 (文法による) モジュール。" -#: ../source/guides/writing-pyproject-toml.rst:311 -msgid "``README.md`` → `GitHub-flavored Markdown `_," -msgstr "``README.md`` → `GitHub 流のマークダウン `_ 、" +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" +"*Python 2* で書かれたプロジェクトにおける、 Python 3 (文法による) モジュー" +"ル。" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/supporting-multiple-python-versions.rst:109 msgid "" -"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +"Because of the bi-directionality, python-future_ offers a pathway to " +"converting a Python 2 package to Python 3 syntax module-by-module. However, " +"in contrast to six_, python-future_ is supported only from Python 2.6. " +"Similar to modernize_ for six_, python-future_ comes with two scripts called " +"``futurize`` and ``pasteurize`` that can be applied to either a Python 2 " +"module or a Python 3 module respectively." msgstr "" -"``README.rst`` → `reStructuredText _`_ (ただし Sphinx 拡張なし)。" - -#: ../source/guides/writing-pyproject-toml.rst:314 -msgid "You can also specify the format explicitly, like this:" -msgstr "次のようにしてフォーマットを明示的に指定することもできます:" - -#: ../source/guides/writing-pyproject-toml.rst:325 -#: ../source/specifications/pyproject-toml.rst:140 -#: ../source/specifications/pyproject-toml.rst:236 -msgid "``license``" -msgstr "``ライセンス``" +"双方向性の故に、 python-future_ は Python 2 で書かれたパッケージをモジュール" +"毎に Python 3 の文法に変換する通路を提供します。しかしながら、 six_ とは異な" +"り、 python-future_ は Python 2.6 からしかサポートされていません。 six_ に対" +"する modernize_ と同様に、 python-future_ は、Python 2 のモジュールに適用でき" +"る ``futurize`` と Python 3 モジュールに適用できる ``pasteurize`` と呼ばれる" +"ふたつのスクリプトを備えています。" -#: ../source/guides/writing-pyproject-toml.rst:327 +#: ../source/guides/supporting-multiple-python-versions.rst:116 msgid "" -"This can take two forms. You can put your license in a file, typically " -"``LICENSE`` or ``LICENSE.txt``, and link that file here:" +"Use of six_ or python-future_ adds an additional runtime dependency to your " +"package: with python-future_, the ``futurize`` script can be called with the " +"``--stage1`` option to apply only the changes that Python 2.6+ already " +"provides for forward-compatibility to Python 3. Any remaining compatibility " +"problems would require manual changes." msgstr "" -"これは、ふたつの形式を採ります。典型的には ``LICENSE`` か ``LICENSE.txt`` と" -"いうファイル名でライセンスをファイルとして置いておいて、ここにはそのファイル" -"へのリンクを書いて置くこともできます:" +"six_ ないし python-future_ を使用すると、追加的な動作時依存性がパッケージに追" +"加されます: python-future_ では ``futurist`` スクリプトを ``--stage1`` オプ" +"ションとともに呼び出すことで Python 2.6 以降に既に備えられた Python 3 との前" +"方互換性を用いる修正だけを行うことができます。残りの互換性問題は、手作業で修" +"正しなければなりません。" -#: ../source/guides/writing-pyproject-toml.rst:335 -msgid "or you can write the name of the license:" -msgstr "あるいは、ライセンスの名称を書いておくことも可能です:" +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "どの Python に何がある？" -#: ../source/guides/writing-pyproject-toml.rst:342 +#: ../source/guides/supporting-multiple-python-versions.rst:125 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.)" +"Ned Batchelder provides a list of changes in each Python release for `Python " +"2 `__, " +"`Python 3.0-3.3 `__ and `Python 3.4-3.6 `__. These lists may be used " +"to check whether any changes between Python versions may affect your package." msgstr "" -"標準的でよく知られたライセンスを使うのであれば、このフィールドを使う必要はあ" -"りません。代わりに、 ``License::`` で始まる :ref:`分類子 ` のう" -"ちのひとつを書いておけば良いでしょう。 (一般的な規則としては標準的でよく知ら" -"れたライセンスを使うことは良い考えです、というのは、混乱を避けるとことにもな" -"るし、中には内部で認可済みのライセンスでなければソフトウェアを使えない組織も" -"あるからです。)" +"Ned Batchelder は、Python の各リリースのそれぞれに一連の修正、つまり、 " +"`Python 2 `__、 `Python 3.0-3.3 `__、 そして `Python 3.4-3.6 `__ を加えるこ" +"とができます。これらのリストは、 Python のバージョン間の変更が特定のパッケー" +"ジに影響を与えるか否かを確認するためにも使えることでしょう。" -#: ../source/guides/writing-pyproject-toml.rst:350 -#: ../source/specifications/pyproject-toml.rst:139 -#: ../source/specifications/pyproject-toml.rst:293 -msgid "``keywords``" -msgstr "``keywords``" +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "Appveyor を用いて Windows をサポートする" -#: ../source/guides/writing-pyproject-toml.rst:352 +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "2015-12-03" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 msgid "" -"This will help PyPI's search box to suggest your project when people search " -"for these keywords." +"This section covers how to use the free `Appveyor`_ continuous integration " +"service to provide Windows support for your project. This includes testing " +"the code on Windows, and building Windows-targeted binaries for projects " +"that use C extensions." msgstr "" -"これは、 PyPI 上の検索でキーワードが与えられた時にこのプロジェクトをサジェス" -"トするのを助けます。" - -#: ../source/guides/writing-pyproject-toml.rst:364 -#: ../source/specifications/pyproject-toml.rst:133 -#: ../source/specifications/pyproject-toml.rst:303 -msgid "``classifiers``" -msgstr "``分類詞 ``" +"この節では、無料の `Appveyor`_ 継続的インテグレーションサービスを使ってあなた" +"のプロジェクトで Windows をサポートする方法について議論します。これには、 " +"Windows におけるソースコードのテストや、 C 言語拡張を含むプロジェクトの " +"Windows 向けのバイナリへのビルドを含みます。" -#: ../source/guides/writing-pyproject-toml.rst:366 +#: ../source/guides/supporting-windows-using-appveyor.rst:19 msgid "" -"A list of PyPI classifiers that apply to your project. Check the `full list " -"of possibilities `_." +"Many projects are developed on Unix by default, and providing Windows " +"support can be a challenge, because setting up a suitable Windows test " +"environment is non-trivial, and may require buying software licenses." msgstr "" -"プロジェクトに合致する PyPI 分類子 のリスト。 `可能な分類子のリ" -"スト `_ を参照してください。" +"多くのプロジェクトが当然のように Unix 上で開発されており、適切なWindows のテ" +"スト環境を準備することが簡単ではないこととソフトウェアライセンスを購入しなけ" +"ればならないであろうことから Windows へのサポートを提供することはある種のチャ" +"レンジになっています。" -#: ../source/guides/writing-pyproject-toml.rst:393 +#: ../source/guides/supporting-windows-using-appveyor.rst:23 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." +"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." msgstr "" -"あるプロジェクトが Python のどのバージョンをサポートしているのかを宣言するた" -"めに分類子 がよく使われますが、この情報は PyPI 上のプロジェクト" -"を検索し閲覧するためにのみ使われるのであって、プロジェクトをインストールする" -"ためには使われません。あるプロジェクトが Python のどのバージョンでならインス" -"トールされ得るのかを実際に制約するためには、 :ref:`requires-python` 引数を" -"使ってください。" +"Appveyor サービスは継続的インテグレーションのサービスであり、 `GitHub`_ にホ" +"ストされたプロジェクトをテストするのによく使われよりよく知られている " +"`Travis`_ サービスによく似ています。しかし、 Travis とは異なり、 Appveyor の" +"ビルドワーカーは Windows であり、 Python の拡張モジュールをビルドするために必" +"要なコンパイラもインストール済みです。" -#: ../source/guides/writing-pyproject-toml.rst:398 +#: ../source/guides/supporting-windows-using-appveyor.rst:29 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 ::``." +"Windows users typically do not have access to a C compiler, and therefore " +"are reliant on projects that use C extensions distributing binary wheels on " +"PyPI in order for the distribution to be installable via ``python -m pip " +"install ``. By using Appveyor as a build service (even if not using it " +"for testing) it is possible for projects without a dedicated Windows " +"environment to provide Windows-targeted binaries." msgstr "" -"パッケージが PyPI にアップロードされるのを防ぐには、 ``Private :: Do Not " -"Upload`` 分類子を使いましょう。``Private ::`` で始まる分類子を付けられたパッ" -"ケージを PyPI は常に拒否します。" +"Windows のユーザは C 言語のコンパイラを持っていないのが普通で、従って、C 言語" +"拡張を使うプロジェクトについては PyPI でバイナリ wheel を配布していなければ " +"``python -m pip install `` 経由で配布物をインスールすることができませ" +"ん。 (たとえテスト目的では利用しなかったとしても) Appveyor をビルドサービスと" +"して利用することで、専用の Windows 環境がなくても Windows 上で動作するバイナ" +"リを準備することができます。" -#: ../source/guides/writing-pyproject-toml.rst:404 -#: ../source/specifications/pyproject-toml.rst:147 -#: ../source/specifications/pyproject-toml.rst:313 -msgid "``urls``" -msgstr "``urls``" +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +msgstr "設定する" -#: ../source/guides/writing-pyproject-toml.rst:406 +#: ../source/guides/supporting-windows-using-appveyor.rst:39 msgid "" -"A list of URLs associated with your project, displayed on the left sidebar " -"of your PyPI project page." +"In order to use Appveyor to build Windows wheels for your project, you must " +"have an account on the service. Instructions on setting up an account are " +"given in `the Appveyor documentation `__. " +"The free tier of account is perfectly adequate for open source projects." msgstr "" -"プロジェクトに関連のある URL のリストで、PyPI 上のプロジェクトページの左サイ" -"ドバーに表示されるもの。" +"Appveyor を用いてプロジェクトの Windows 向けの wheel をビルドするためには、こ" +"のサービスのアカウントを持っていなければなりません。アカウントの設定に関する" +"説明は `the Appveyor documentation `__ にあり" +"ます。オープンソースプロジェクトには無料アカウントで十分です。" -#: ../source/guides/writing-pyproject-toml.rst:418 +#: ../source/guides/supporting-windows-using-appveyor.rst:44 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\"``." +"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 "" -"もしキーが空白文字を含んでいるなら、例えば ``Website = \"https://example." -"com\"`` ではなくて ``\"Official Website\" = \"https://example.com\"`` のよう" -"に引用符で囲む必要があります。" +"Appveyor では `GitHub`_ や `BitBucket`_ との統合運用ができるので、プロジェク" +"トがこれらのうちのいずれかにホストされている限りは Appveyor から統合運用する" +"設定は簡単にできます。" -#: ../source/guides/writing-pyproject-toml.rst:425 -msgid "Advanced plugins" -msgstr "先進的なプラグイン" +#: ../source/guides/supporting-windows-using-appveyor.rst:48 +msgid "" +"Once you have set up your Appveyor account and added your project, Appveyor " +"will automatically build your project each time a commit occurs. This " +"behaviour will be familiar to users of Travis." +msgstr "" +"Appveyor のアカウントの設定とプロジェクトの追加が終われば、コミットが発生する" +"たびに Appveyor が自動的にプロジェクトをビルドするようになります。Travis の" +"ユーザはこのような動作に慣れていることでしょう。" -#: ../source/guides/writing-pyproject-toml.rst:427 +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "プロジェクトに Appveyor サポートを追加する" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 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:" +"In order to define how Appveyor should build your project, you need to add " +"an :file:`appveyor.yml` file to your project. The full details of what can " +"be included in the file are covered in the Appveyor documentation. This " +"guide will provide the details necessary to set up wheel builds." msgstr "" -"パッケージの中にはプラグインを使って拡張できるものがあります。例としては、" -"Pytest_ や Pygments_ が挙げられます。そのようなプラグインを作成するためには、" -"以下のように ``[project.entry-points]`` のサブテーブルで宣言する必要がありま" -"す:" +"Appveyor がプロジェクトをビルドする方法を定義するためには、 :file:`appveyor." +"yml` ファイルをプロジェクトに追加する必要があります。このファイルに書くことが" +"できる項目の完全な細部は、 Appveyor の説明文書で説明されています。このガイド" +"では、wheel のビルドに必要な部分に限って細部を説明します。" -#: ../source/guides/writing-pyproject-toml.rst:436 -msgid "See the :ref:`Plugin guide ` for more information." +#: ../source/guides/supporting-windows-using-appveyor.rst:60 +msgid "" +"Appveyor includes by default all of the compiler toolchains needed to build " +"extensions for Python. For Python 2.7, 3.5+ and 32-bit versions of 3.3 and " +"3.4, the tools work out of the box. But for 64-bit versions of Python 3.3 " +"and 3.4, there is a small amount of additional configuration needed to let " +"distutils know where to find the 64-bit compilers. (From 3.5 onwards, the " +"version of Visual Studio used includes 64-bit compilers with no additional " +"setup)." msgstr "" -"詳しくは、 :ref:`プラグインガイド ` を見てください。" +"Appveyor は、Python 向けの拡張モジュールをビルドするために必要なすべてのコン" +"パイラ・ツールチェーンをデフォルトで含んでいます。 Python 2.7 ・ 3.5+ 、およ" +"び 32 ビット版の 3.3 と 3.4 向けであれば、このツールはそのままで動作します。" +"しかし、 64 ビット版の 3.3 と 3.4 では、 distutils が 64 ビット版のコンパイラ" +"を検出できるように少量の追加的な設定が必要です。( 3.5 以降については、追加の" +"設定をしなくても Visual Studio の各バージョンに含まれている 64 ビット版コンパ" +"イラを使います)。" -#: ../source/guides/writing-pyproject-toml.rst:441 -msgid "A full example" -msgstr "完全な例" +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "appveyor.yml" -#: ../source/guides/writing-pyproject-toml.rst:503 +#: ../source/guides/supporting-windows-using-appveyor.rst:74 msgid "" -"Think twice before applying an upper bound like ``requires-python = \"<= " -"3.10\"`` here. `This blog post `_ contains some " -"information regarding possible problems." +"This file can be downloaded from `here `__." msgstr "" -"ここで ``requires-python = \"<=3.10\"`` のような上限を設定する前に、よくよく" -"考えてください。起きる可能性のある問題に関するいくらかの情報が `このブログ記" -"事 `_ にあります。" +"このファイルは `ここ `__ か" +"らダウンロードすることができます。" -#: ../source/index.rst:-1 +#: ../source/guides/supporting-windows-using-appveyor.rst:76 msgid "" -"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " -"guides for packaging Python software." +"The :file:`appveyor.yml` file must be located in the root directory of your " +"project. It is in ``YAML`` format, and consists of a number of sections." msgstr "" -"Python パッケージングユーザガイド (PyPUG) は、Python ソフトウェアのパッケージ" -"ングに関するチュートリアルやガイドを集めたものです。" - -#: ../source/index.rst:-1 -msgid "python, packaging, guide, tutorial" -msgstr "python ・ パッケージング・ガイド・チュートリアル" - -#: ../source/index.rst:3 ../source/key_projects.rst:247 -msgid "Python Packaging User Guide" -msgstr "Pythonパッケージユーザーガイド（Python Packaging User Guide）" +":file:`appveyor.yml` ファイルは、プロジェクトのルートディレクトリに置かなけれ" +"ばなりません。このファイルは ``YAML`` フォーマットで書かれていて、数多くのセ" +"クションから構成されています。" -#: ../source/index.rst:25 +#: ../source/guides/supporting-windows-using-appveyor.rst:79 msgid "" -"Welcome to the *Python Packaging User Guide*, a collection of tutorials and " -"references to help you distribute and install Python packages with modern " -"tools." +"The ``environment`` section is the key to defining the Python versions for " +"which your wheels will be created. Appveyor comes with Python 2.6, 2.7, 3.3, " +"3.4 and 3.5 installed, in both 32-bit and 64-bit builds. The example file " +"builds for all of these environments except Python 2.6. Installing for " +"Python 2.6 is more complex, as it does not come with pip included. We don't " +"support 2.6 in this document (as Windows users still using Python 2 are " +"generally able to move to Python 2.7 without too much difficulty)." msgstr "" -"*Python パッケージングユーザガイド* へようこそ、チュートリアルとリファレンス" -"であなたが近代的なツールを使ってパッケージを配布・インストールするのをお手伝" -"いします。" +"``environment`` は、どのバージョンの Python 向けに wheel を生成するかを定義す" +"る鍵となるセクションです。 Appveyor には 32 ビット版と 64 ビット版の両方の " +"Python 2.6, 2.7, 3.3, 3.4, 3.5 が予めインストールされています。例示したファイ" +"ルでは、 Python 2.6 を除くこれらすべての環境向けにビルドするようになっていま" +"す。 Python 2.6 は pip を含まないので、これをインストールすることはより複雑で" +"す。このドキュメントでは、 Python 2.6 はサポートしません (Windows ユーザでま" +"だ Python 2 を使っているユーザであれば、大抵は大した困難に遭遇せずに Python " +"2.7 へ移行できるからです) 。" -#: ../source/index.rst:29 +#: ../source/guides/supporting-windows-using-appveyor.rst:87 msgid "" -"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " -"Authority `. We happily accept :doc:`contributions and feedback " -"`. 😊" +"The ``install`` section uses pip to install any additional software that the " +"project may require. The only requirement for building wheels is the " +"``wheel`` project, but projects may wish to customise this code in certain " +"circumstances (for example, to install additional build packages such as " +"``Cython``, or test tools such as ``tox``)." msgstr "" -"このガイドは、:doc:`Python パッケージングオーソリティ ` によって " -"`GitHub`_ 上で維持管理されています。:doc:`貢献とフィードバック ` " -"を大いに歓迎します。😊" - -#: ../source/index.rst:36 -msgid "Overview and Flow" -msgstr "概要と流れ" +"``install`` セクションは、プロジェクトが必要とする追加的なソフトウェアを pip " +"を使ってインストールするのに使われます。 wheel をビルドするために必要なもの" +"は ``wheel`` プロジェクトだけですが、プロジェクトによっては特定の環境下ではこ" +"の項をカスタマイズしたいと思うかもしれません (例えば、 ``Cython`` のような追" +"加的なビルド用パッケージないし ``tox`` のようなテストツールをインストールする" +"ために)。" -#: ../source/index.rst:40 +#: ../source/guides/supporting-windows-using-appveyor.rst:93 msgid "" -"Building your understanding of Python packaging is a journey. Patience and " -"continuous improvement are key to success. The overview and flow sections " -"provide a starting point for understanding the Python packaging ecosystem." +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." msgstr "" -"Python のパッケージングに関する理解を醸成することは旅をするようなものです。忍" -"耐と継続的な改善が成功への鍵となります。概要と流れの章では、Python のパッケー" -"ジングのエコシステムを理解するための出発点を提供します。" +"``build`` セクションでは単純にビルドのスイッチを切りましょう - ``C#`` のよう" +"な言語とは異なり、Python にはビルドする段階は不要なのです。" -#: ../source/index.rst:44 +#: ../source/guides/supporting-windows-using-appveyor.rst:96 msgid "" -"The :doc:`overview` 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." +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." msgstr "" -":doc:`概要 ` では、 Python でのパッケージングとプロジェクトを準備し" -"て配布する時にどのように使うかを説明します。この節では、ツールの選定やユース" -"ケースに最適なプロセスについての理解を醸成します。パッケージングとは何か、そ" -"れが解決する問題、そして鍵となる考慮事項を含みます。" +"個々のプロジェクト向けに整える必要のある主なセクションは、 ``test_script`` " +"と ``after_test`` です。" -#: ../source/index.rst:51 +#: ../source/guides/supporting-windows-using-appveyor.rst:99 msgid "" -"To get an overview of the workflow used to publish your code, see :doc:" -"`packaging flow `." +"The ``test_script`` section is where you will run your project's tests. The " +"supplied file runs your test suite using ``setup.py test``. If you are only " +"interested in building wheels, and not in running your tests on Windows, you " +"can replace this section with a dummy command such as ``echo Skipped " +"Tests``. You may wish to use another test tool, such as ``nose`` or :file:" +"`py.test`. Or you may wish to use a test driver like ``tox`` - however if " +"you are using ``tox`` there are some additional configuration changes you " +"will need to consider, which are described below." msgstr "" -"あなたのソースコードを公開するために用いられるワークフローの概要を得たけれ" -"ば、 :doc:`パッケージングフロー ` を見てください。" +"``test_script`` セクションは、プロジェクトのテストを走らせる場所です。与えら" +"れたファイルを使って ``setup.py test`` を走らせることで一連のテストを行いま" +"す。wheel ファイルをビルドすることだけに興味があるのであれば、そして、 " +"Windows でテストをしないのであれば、このセクションに ``echo Skipped Tests`` " +"のようなダミーコマンドを書いておけば良いでしょう。 ``nose`` や :file:`py." +"test` のような他のテストツールを使いたい場合があるかもしれません。あるいは、 " +"``tox`` のようなテストドライバを使いたいと思うかもしれません - しかしなが" +"ら、 ``tox`` を使う場合には、後述の通り、もう少し追加の設定変更を検討する必要" +"があることでしょう。" -#: ../source/index.rst:57 +#: ../source/guides/supporting-windows-using-appveyor.rst:108 msgid "" -"Tutorials walk through the steps needed to complete a project for the first " -"time. Tutorials aim to help you succeed and provide a starting point for " -"future exploration. The :doc:`tutorials/index` section includes:" +"The ``after_test`` runs once your tests have completed, and so is where the " +"wheels should be built. Assuming your project uses the recommended tools " +"(specifically, ``setuptools``) then the ``setup.py bdist_wheel`` command " +"will build your wheels." msgstr "" -"チュートリアルでは、初めてプロジェクトを完成させる際に必要な諸段階を一通り眺" -"めます。チュートリアルは、将来の探検のための出発点を提供することであなたの成" -"功を助けます。 :doc:`チュートリアル ` の節には次のものが含ま" -"れます:" +"``after_test`` は、テストが完了したあとに一度だけ走り、したがって、ここで " +"wheel ファイルを生成するべきです。あなたのプロジェクトで推奨ツール (とりわけ " +"``setuptools``) を使っているなら、 ``setup.py bdist_wheel`` コマンドで wheel " +"ファイルを生成できます。" -#: ../source/index.rst:62 +#: ../source/guides/supporting-windows-using-appveyor.rst:113 msgid "" -"A :doc:`tutorial on installing packages `" +"Note that wheels will only be built if your tests succeed. If you expect " +"your tests to fail on Windows, you can skip them as described above." msgstr "" -":doc:`パッケージをインストールするためのチュートリアル `" +"テストが成功した場合にだけ wheel ファイルが生成されるという点に留意してくださ" +"い。 Windows ではテストが失敗するとわかっているなら、前述の通り、それを省略す" +"ることができます。" -#: ../source/index.rst:63 +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "サポートスクリプト" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 msgid "" -"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +"The :file:`appveyor.yml` file relies on a single support script, which sets " +"up the environment to use the SDK compiler for 64-bit builds on Python 3.3 " +"and 3.4. For projects which do not need a compiler, or which don't support " +"3.3 or 3.4 on 64-bit Windows, only the :file:`appveyor.yml` file is needed." msgstr "" -"バージョンを管理しているプロジェクトでの :doc:`アプリケーションの依存関係を管" -"理するためのチュートリアル `" +":file:`appveyor.yml` ファイルは、Python 3.3 と 3.4 上で 64 ビットでのビルドを" +"行うために SDK のコンパイラを使う環境を構築するためのひとつのサポートスクリプ" +"トに依存しています。コンパイラを必要としないプロジェクトや64 ビット版の " +"Windows 上の 3.3 や 3.4 をサポートしないプロジェクトでは、 :file:`appveyor." +"yml` ファイルさえあれば良いことになります。" -#: ../source/index.rst:65 +#: ../source/guides/supporting-windows-using-appveyor.rst:125 msgid "" -"A :doc:`tutorial on packaging and distributing ` your project" +"`build.cmd `__ is a Windows batch " +"script that runs a single command in an environment with the appropriate " +"compiler for the selected Python version. All you need to do is to set the " +"single environment variable ``DISTUTILS_USE_SDK`` to a value of ``1`` and " +"the script does the rest. It sets up the SDK needed for 64-bit builds of " +"Python 3.3 or 3.4, so don't set the environment variable for any other " +"builds." msgstr "" -"あなたのプロジェクトの :doc:`パッケージングと配布のためのチュートリアル " -"`" +"`build.cmd `__ は、選択されたバー" +"ジョンの Python 用の適切なコンパイラが存在する環境内で単一のコマンドを実行す" +"るような Windows のバッチスクリプトです。やらなければならないことはたった一個" +"の環境変数 ``DISTUTILS_USE_SDK`` の値を ``1`` に設定することだけで、残りはす" +"べてこのスクリプトがやってくれます。スクリプトが Python 3.3 ないし 3.4 を 64 " +"ビットでビルドするのに必要な SDK 環境を構築するので、他のビルドに使う環境変数" +"を設定してはいけません。" -#: ../source/index.rst:71 +#: ../source/guides/supporting-windows-using-appveyor.rst:132 msgid "" -"Guides provide steps to perform a specific task. Guides are more focused on " -"users who are already familiar with Python packaging and are looking for " -"specific information." +"You can simply download the batch file and include it in your project " +"unchanged." msgstr "" -"ガイド文書は、特定のタスクを実行するためのステップを提供します。ガイド文書" -"は、すでに Python のパッケージングに慣れていて、特定の情報を探しているような" -"ユーザに、より強く焦点を合わせています。" +"このバッチファイルは単純にダウンロードして修正なしにプロジェクト内に置くこと" +"ができます。" -#: ../source/index.rst:75 +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "ビルドされたwheelファイルへのアクセス" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 msgid "" -"The :doc:`guides/index` section provides \"how to\" instructions in three " -"major areas: package installation; building and distributing packages; " -"miscellaneous topics." +"When your build completes, the built wheels will be available from the " +"Appveyor control panel for your project. They can be found by going to the " +"build status page for each build in turn. At the top of the build output " +"there is a series of links, one of which is \"Artifacts\". That page will " +"include a list of links to the wheels for that Python version / " +"architecture. You can download those wheels and upload them to PyPI as part " +"of your release process." msgstr "" -":doc:`ガイド ` 節では、パッケージインストール; パッケージの作成" -"と配布; その他の話題という３個の主要な分野について \"ハウツー \" とな" -"る指示を提供します。" +"ビルドが終わると、出来上がった wheel ファイルは Appveyor のコントロールパネル" +"の当該プロジェクトのページから取り出せるでしょう。ビルドのたびに生成されるビ" +"ルド状況のページからも取り出せます。ビルド結果の出力ページの先頭には一連のリ" +"ンクがあって、そのうちの \"Artifacts\" がそれです。そのページに行くと該当する" +"バージョンの Python / アーキテクチャに応じた wheel ファイルへのリンクがあるは" +"ずです。ここから wheel ファイルをダウンロードして、あなたのリリース作業の一環" +"として PyPI へアップロードすることができるでしょう。" -#: ../source/index.rst:80 -msgid "Explanations and Discussions" -msgstr "説明と議論" +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "tox を用いてテストする" -#: ../source/index.rst:82 +#: ../source/guides/supporting-windows-using-appveyor.rst:151 msgid "" -"The :doc:`discussions/index` section for in-depth explanations and " -"discussion about topics, such as:" -msgstr "" -"以下に述べるような話題に関する詳細に渡る説明と議論のための :doc:`議論 " -"` の節:" - -#: ../source/index.rst:85 -msgid ":doc:`discussions/deploying-python-applications`" +"Many projects use the :doc:`Tox ` tool to run their tests. It " +"ensures that tests are run in an isolated environment using the exact files " +"that will be distributed by the project." msgstr "" -":doc:`議論/Pythonアプリの設置 `" - -#: ../source/index.rst:86 -msgid ":doc:`discussions/pip-vs-easy-install`" -msgstr ":doc:`議論/pip対easy-install `" - -#: ../source/index.rst:89 -msgid "Reference" -msgstr "参考文献" +"多くのプロジェクトで :doc:`Tox ` ツールを用いてテストを行っていま" +"す。これを使えば、プロジェクトで配布するであろうファイル群そのものを使った独" +"立した環境下でテストを実行することができます。" -#: ../source/index.rst:91 +#: ../source/guides/supporting-windows-using-appveyor.rst:155 msgid "" -"The :doc:`specifications/index` section for packaging interoperability " -"specifications." +"In order to use ``tox`` on Appveyor there are a couple of additional " +"considerations (in actual fact, these issues are not specific to Appveyor, " +"and may well affect other CI systems)." msgstr "" -"パッケージングに関する相互運用性の仕様については、 :doc:`仕様 " -"` を見てください。" +"Appveyor 上で ``tox`` を使うためには、(実際のところは、Appveyor に限ったこと" +"ではなく、他の CI システムにも影響します) いくつかの追加的な事項を検討しなけ" +"ればなりません。" -#: ../source/index.rst:92 +#: ../source/guides/supporting-windows-using-appveyor.rst:159 msgid "" -"The list of :doc:`other projects ` maintained by members of " -"the Python Packaging Authority." +"By default, ``tox`` only passes a chosen subset of environment variables to " +"the test processes. Because ``distutils`` uses environment variables to " +"control the compiler, this \"test isolation\" feature will cause the tests " +"to use the wrong compiler by default." msgstr "" -"Python パッケージングオーソリティのメンバーが維持管理している :doc:`他のプロ" -"ジェクト群 ` のリスト。" +"デフォルトでは ``tox`` は、環境変数のうちのいくつかの選択されたサブセットだけ" +"をテストプロセスに渡します。 ``distutils`` がコンパイラを制御するのに環境変数" +"を用いるので、この \"テスト環境分離\" の機能がデフォルトではテストに誤ったコ" +"ンパイラを使ってしまう問題を引き起こすでしょう。" -#: ../source/index.rst:93 -msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +#: ../source/guides/supporting-windows-using-appveyor.rst:164 +msgid "" +"To force ``tox`` to pass the necessary environment variables to the " +"subprocess, you need to set the ``tox`` configuration option ``passenv`` to " +"list the additional environment variables to be passed to the subprocess. " +"For the SDK compilers, you need" msgstr "" -"Python パッケージングで使われる用語の定義についての :doc:`語彙集 " -"` 。" +"``tox`` がサブプロセスに必要な環境変数を渡すように強制するためには、 ``tox`` " +"の設定オプションである ``passenv`` に追加的にサブプロセスに渡すべき環境変数の" +"リストを設定する必要があります。SDK コンパイラを使うのであれば、このような設" +"定が必要です" -#: ../source/key_projects.rst:6 -msgid "Project Summaries" -msgstr "プロジェクト概要" +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "``DISTUTILS_USE_SDK``" -#: ../source/key_projects.rst:8 -msgid "" -"Summaries and links for the most relevant projects in the space of Python " -"installation and packaging." -msgstr "" -"Python の実装やパッケージングの領域で最も関連があるプロジェクト群へのまとめと" -"リンク。" +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "``MSSdk``" -#: ../source/key_projects.rst:14 -msgid "PyPA Projects" -msgstr "PyPA プロジェクト群" +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "``INCLUDE``" -#: ../source/key_projects.rst:19 -msgid "bandersnatch" -msgstr "bandersnatch" +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +msgstr "``LIB``" -#: ../source/key_projects.rst:21 +#: ../source/guides/supporting-windows-using-appveyor.rst:174 msgid "" -"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +"The ``passenv`` option can be set in your :file:`tox.ini`, or if you prefer " +"to avoid adding Windows-specific settings to your general project files, it " +"can be set by setting the ``TOX_TESTENV_PASSENV`` environment variable. The " +"supplied :file:`build.cmd` script does this by default whenever " +"``DISTUTILS_USE_SDK`` is set." msgstr "" -"`説明文書 `__ | `課題リスト `__ | `GitHub `__ | `PyPI `__" +"``passenv`` オプションは、 :file:`tox.ini` ファイルでも設定可能で、あるいは、" +"Windows 特有の設定をプロジェクト全体のファイル群に追加したくなければ " +"``TOX_TESTENV_PASSENV`` 環境変数でも設定できます。 ``DISTUTILS_USE_SDK`` が設" +"定されていればいつでも、与えられた :file:`build.cmd` スクリプトがこの動作をデ" +"フォルトで実行します。" -#: ../source/key_projects.rst:26 +#: ../source/guides/supporting-windows-using-appveyor.rst:180 msgid "" -"``bandersnatch`` is a PyPI mirroring client designed to efficiently create a " -"complete mirror of the contents of PyPI. Organizations thus save bandwidth " -"and latency on package downloads (especially in the context of automated " -"tests) and to prevent heavily loading PyPI's Content Delivery Network (CDN). " -"Files can be served from a local directory or `AWS S3`_." +"When used interactively, ``tox`` allows you to run your tests against " +"multiple environments (often, this means multiple Python versions). This " +"feature is not as useful in a CI environment like Travis or Appveyor, where " +"all tests are run in isolated environments for each configuration. As a " +"result, projects often supply an argument ``-e ENVNAME`` to ``tox`` to " +"specify which environment to use (there are default environments for most " +"versions of Python)." msgstr "" -"``bandersnatch`` は、PyPI をミラーリングするクライアントで、PyPI のコンテンツ" -"の完全なコピーを効率よく作成するように設計されています。組織から見ると、これ" -"によってパッケージのダウンロードに必要な帯域幅とレイテンシーを (とりわけ自動" -"化されたテストの文脈で) 節約することができ、PyPI のコンテンツデリバリネット" -"ワーク (CDN) への負荷を軽減します。ローカルのディレクトリからでも `AWS S3`_ " -"からでもファイル群を提供するようにできます。" - -#: ../source/key_projects.rst:37 -msgid "build" -msgstr "ビルド" +"``tox`` を対話的に使うと、複数の環境 (これはしばしば複数のバージョンの " +"Python を意味します) でテストを実行することができます。設定ごとに独立した環境" +"ですべてのテストを実行する Travis や Appveyor のような CI 環境で見られるほど" +"には、この機能は有用ではありません。結果として、しばしばプロジェクト側から " +"``-e ENVNAME`` 引数を ``tox`` に与えてどの環境を使うべきか (ほとんどのバー" +"ジョンの Python に対応したデフォルトの環境群があります) を指定します。" -#: ../source/key_projects.rst:39 +#: ../source/guides/supporting-windows-using-appveyor.rst:187 msgid "" -":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +"However, this does *not* work well with a Windows CI system like Appveyor, " +"where there are (for example) two installations of Python 3.4 (32-bit and 64-" +"bit) available, but only one ``py34`` environment in ``tox``." msgstr "" -":any:`文書 ` | `課題リスト `__ | `GitHub `__ | `PyPI `__" +"しかしながら、このやり方は、 Appveyor のような Windows 上の CI システムでは " +"(例えば) Python 3.4 の (32 版ビットと64ビット版の) ふたつの実装が利用できるの" +"に、 ``tox`` では ``py34`` 環境がひとつしかないので、うまく動きません。" -#: ../source/key_projects.rst:44 +#: ../source/guides/supporting-windows-using-appveyor.rst:191 msgid "" -"``build`` is a :pep:`517` compatible Python package builder. It provides a " -"CLI to build packages, as well as a Python API." +"In order to run tests using ``tox``, therefore, projects should probably use " +"the default ``py`` environment in ``tox``, which uses the Python interpreter " +"that was used to run ``tox``. This will ensure that when Appveyor runs the " +"tests, they will be run with the configured interpreter." msgstr "" -"``build`` は :pep:`517` 互換の Python パッケージビルダです。Python API と同様" -"に、パッケージをビルドする CLI を提供します。" - -#: ../source/key_projects.rst:51 -msgid "cibuildwheel" -msgstr "cibuildwheel" +"``tox`` を使ってテストを実行するためには、したがって、プロジェクトがおそらく" +"は ``tox`` のデフォルトの ``py`` 環境、ここでは ``tox`` を実行するために使わ" +"れた Python インタープリタを使うことになりますが、その環境を使うべきでしょ" +"う。" -#: ../source/key_projects.rst:53 +#: ../source/guides/supporting-windows-using-appveyor.rst:196 msgid "" -"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " -"`Discussions `__ | " -"`Discord #cibuildwheel `__" +"In order to support running under the ``py`` environment, it is possible " +"that projects with complex ``tox`` configurations might need to modify " +"their :file:`tox.ini` file. Doing so is, however, outside the scope of this " +"document." msgstr "" -"`説明文書 `__ | `課題リスト `__ | `GitHub `__ | `PyPI `__ | `議論 " -"`__ | `Discord " -"#cibuildwheel `__" +"``py`` 環境下での動作をサポートするためには、複雑な ``tox`` 設定を持つプロ" +"ジェクトでは :file:`tox.ini` を修正する必要があるかもしれません。そのようにす" +"ることは、しかしながら、この文書の範囲を越えます。" -#: ../source/key_projects.rst:60 +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "自動的に wheel ファイルをアップロードする" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 msgid "" -"``cibuildwheel`` is a Python package that builds :term:`wheels ` for " -"all common platforms and Python versions on most CI systems. Also see :ref:" -"`multibuild`." +"It is possible to request Appveyor to automatically upload wheels. There is " +"a ``deployment`` step available in :file:`appveyor.yml` that can be used to " +"(for example) copy the built artifacts to a FTP site, or an Amazon S3 " +"instance. Documentation on how to do this is included in the Appveyor guides." msgstr "" -"``cibuildwheel`` は、プラットフォーム・ Python バージョン・ CIシステムのよく" -"ある組み合わせの全部について :term:`wheels ` をビルドする Python パッ" -"ケージです。" - -#: ../source/key_projects.rst:66 -msgid "distlib" -msgstr "distlib" +"Appveyor に自動的に wheel ファイルをアップロードさせることができます。 :file:" +"`appveyor.yml` ファイルの中に ``deployment`` 段階があって、(例えば) ビルドし" +"た生成物を FTP サイトや Amazon S3 インスタンスへコピーするために使うことがで" +"きます。これをやるにはどうすれば良いかについては、 Appveyor ガイドに説明があ" +"ります。" -#: ../source/key_projects.rst:68 +#: ../source/guides/supporting-windows-using-appveyor.rst:209 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +"Alternatively, it would be possible to add a ``twine upload`` step to the " +"build. The supplied :file:`appveyor.yml` does not do this, as it is not " +"clear that uploading new wheels after every commit is desirable (although " +"some projects may wish to do this)." msgstr "" -":doc:`文書 ` | `課題リスト `__ | `GitHub `__ | `PyPI `__" +"別のやり方としては、ビルドの際に ``twine upload`` 段階を追加することができる" +"でしょう。 (プロジェクトによってはそうしたいかもしれませんが) コミットのたび" +"に新しい wheel ファイルをアップロードすることが望ましいかどうかがはっきりしな" +"いので、先ほどの :file:`appveyor.yml` ファイルはこれをやりません。" -#: ../source/key_projects.rst:73 +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "外部への依存関係" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 msgid "" -"``distlib`` is a library which implements low-level functions that relate to " -"packaging and distribution of Python software. ``distlib`` implements " -"several relevant PEPs (Python Enhancement Proposal standards) and is useful " -"for developers of third-party packaging tools to make and upload binary and " -"source :term:`distributions `, achieve " -"interoperability, resolve dependencies, manage package resources, and do " -"other similar functions." +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." msgstr "" -"``distlib`` は、 Python ソフトウェアのパッケージングや配布に関係する低レベル" -"の機能を実装しているライブラリです。 ``distlib`` はいくつかの関連する PEP " -"(Python Enhancement Proposal standards) を実装していて、サードパーティのパッ" -"ケージングツールの開発者にとってバイナリやソースコードの :term:`配布物 " -"` を作成・アップロードしたり、相互運用性を確保したり、" -"依存関係を解決したり、パッケージリソースを管理したり、その他の類似の機能を実" -"行したりするのに便利です。" +"提供されたスクリプトを使えば、ビルド時にサードパーティの外部ライブラリに依存" +"しない配布物ならどれでもビルドに成功するでしょう。" -#: ../source/key_projects.rst:82 +#: ../source/guides/supporting-windows-using-appveyor.rst:220 msgid "" -"Unlike the stricter :ref:`packaging` project (below), which specifically " -"implements modern Python packaging interoperability standards, ``distlib`` " -"also attempts to provide reasonable fallback behaviours when asked to handle " -"legacy packages and metadata that predate the modern interoperability " -"standards and fall into the subset of packages that are incompatible with " -"those standards." +"It is possible to add steps to the :file:`appveyor.yml` configuration " +"(typically in the \"install\" section) to download and/or build external " +"libraries needed by the distribution. And if needed, it is possible to add " +"extra configuration for the build to supply the location of these libraries " +"to the compiler. However, this level of configuration is beyond the scope of " +"this document." msgstr "" -"近代的な Python パッケージングにおける相互運用性標準に特に気を配って実装され" -"た、より厳格な :ref:`packaging` プロジェクト (後述) とは異なり、 ``distlib`` " -"は近代的な相互運用性標準ができる前の昔ながらのパッケージやメタデータで今と" -"なってはその標準に外れたことになっているものを扱うように言われた時には合理的" -"なフォールバック動作も提供しようとしています。" +":file:`appveyor.yml` ファイルでの設定 (典型的には \"install\" 段階) を加え" +"て、配布物に必要な外部ライブラリをダウンロードないしビルドすることは可能で" +"す。そして、もし必要なら、このようなライブラリの位置ををコンパイラに伝えるた" +"めの余分の設定を追加することもできます。しかしながら、このレベルの設定はこの" +"文書の範囲を超えます。" -#: ../source/key_projects.rst:93 -msgid "distutils" -msgstr "distutils" +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "サポートスクリプト" -#: ../source/key_projects.rst:95 -msgid "" -"The original Python packaging system, added to the standard library in " -"Python 2.0 and removed in 3.12." -msgstr "" -"Python の元々のパッケージングシステムで、Python 2.0 の時点で標準ライブラリに" -"追加され 3.12 で削除されました。" +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "参照用に SDK を構築するサポートスクリプトをここに挙げておきます:" -#: ../source/key_projects.rst:98 +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "``appveyor-sample/build.cmd``" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "オススメのツール" + +#: ../source/guides/tool-recommendations.rst:7 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` has been 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." +"The Python packaging landscape consists of many different tools. For many " +"tasks, the :term:`Python Packaging Authority ` (PyPA, the working group which encompasses many packaging tools and " +"maintains this guide) purposefully does not make a blanket recommendation; " +"for example, the reason there are many build backends is that the landscape " +"was opened up in order to enable the development of new backends serving " +"certain users' needs better than the previously unique backend, setuptools. " +"This guide does point to some tools that are widely recognized, and also " +"makes some recommendations of tools that you should *not* use because they " +"are deprecated or insecure." msgstr "" -"パッケージングシステムを維持管理する際の難題には機能向上が言語ラインタイムの" -"更新と密接に結びついていることが挙げられますが、そのせいで :ref:`distutils` " -"を直接に使用することは強い非推奨事項にずっとなり続けてきており、代わりに :" -"ref:`Setuptools` を使うことが望ましいとされています。 :ref:`Setuptools` " -"は、 :ref:`distutils` そのものが提供していない機能 (例えば依存関係の宣言やエ" -"ントリポイントの宣言) を提供できるだけでなく、守備一貫したビルド用のインタ" -"フェイスやサポートするすべてのバージョンの Python のすべてについて設定できる" -"機能を提供しています。" +"Python パッケージングのランドスケープは、多くの異なったツール群からできていま" +"す。多くのタスクについて、 :term:`Python パッケージングオーソリティ ` (PyPA とは多数のパッケージングツール群を包含す" +"るとともにこのガイド文書を維持管理しているワーキンググループ) は、一律に適用" +"するような推奨ををしません; 例えば、数多くのビルドバックエンドが存在する理由" +"は、既存のユニークなバックエンドである setuptools よりもうまく特定のユーザの" +"ニーズに応える新しいバックエンドの開発を可能とするためにランドスケープを開放" +"しているということなのです。このガイド文書では、広く認知されている幾つかの" +"ツールを指し示していますが、また、非推奨であったり安全でなかったりするために " +"*使うべきでない* ものについても非推奨事項を記しています。" -#: ../source/key_projects.rst:107 +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "仮想環境" + +#: ../source/guides/tool-recommendations.rst:22 msgid "" -"Consequently, :ref:`distutils` was deprecated in Python 3.10 by :pep:`632` " -"and has been :doc:`removed ` from the standard library " -"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." +"The standard tools to create and use virtual environments manually are :ref:" +"`virtualenv` (PyPA project) and :doc:`venv ` (part of " +"the Python standard library, though missing some features of virtualenv)." msgstr "" -"従って、 :ref:`distutils` は :pep:`632` によって Python 3.10 で非推奨にな" -"り、 Python 3.12 で標準ライブラリから :doc:`削除 ` され" -"ました。Setuptools にはスタンドアローンの distutils が同梱されていて、< 3.12 " -"の Python 上であっても setuptools をインポートするか pip を使うと注入されま" -"す。" +"仮想環境を手動で作成して使用するための標準的なツールは、 :ref:`virtualenv` " +"(PyPA project) と :doc:`venv ` (virtualenv には備わって" +"いる幾つかの機能が欠けてはいるものの、Pythonの標準ライブラリの一部) です。" -#: ../source/key_projects.rst:116 -msgid "flit" -msgstr "flit" +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "パッケージをインストールする" -#: ../source/key_projects.rst:118 +#: ../source/guides/tool-recommendations.rst:30 msgid "" -"`Docs `__ | `Issues `__ | `PyPI `__" +":ref:`Pip` is the standard tool to install packages from :term:`PyPI `. You may want to read pip's recommendations for :doc:" +"`secure installs `. Pip is available by default " +"in most Python installations through the standard library package :doc:" +"`ensurepip `." msgstr "" -"`説明文書 `__ | `課題リスト `__ | `PyPI `__" +":ref:`Pip` は :term:`PyPI ` からパッケージをイン" +"ストールするための標準的なツールです。 pip の推奨事項については、 :doc:`セ" +"キュアなインストール ` を読むと良いでしょう。 " +"pip は、標準ライブラリのパッケージ :doc:`ensurepip ` を通じて、ほとんどの Python 環境でデフォルトで利用可能です。" -#: ../source/key_projects.rst:122 +#: ../source/guides/tool-recommendations.rst:36 msgid "" -"Flit provides a simple way to create and upload pure Python packages and " -"modules to PyPI. It focuses on `making the easy things easy `_ for packaging. Flit can generate a configuration file to " -"quickly set up a simple project, build source distributions and wheels, and " -"upload them to PyPI." +"Alternatively, consider :ref:`pipx` for the specific use case of installing " +"Python applications that are distributed through PyPI and run from the " +"command line. Pipx is a wrapper around pip and venv that installs each " +"application into a dedicated virtual environment. This avoids conflicts " +"between the dependencies of different applications, and also with system-" +"wide applications making use of the same Python interpreter (especially on " +"Linux)." msgstr "" -"Flit は、純 Python のパッケージやモジュールを作成して PyPI へアップロードする" -"簡単な手段を提供します。パッケージングに関して `簡単なことを簡単に実現する " -"`_ ことに注力しています。これを使えば単純なプロジェクトや" -"ソースコード配布物とwheelsについて素早くセットアップするための設定ファイルを" -"生成し、PyPI にアップロードすることができます。" +"別のやり方としては、 PyPI を通じて配布されてコマンドラインから実行される " +"Python アプリケーションをインストールする特定のユースケースにおいては :ref:" +"`pipx` を検討してください。 pipx は pip と、専用の仮想環境の中にそれぞれのア" +"プリケーションをインストールする venv のラッパーとして動作します。これによっ" +"て、異なるアプリケーションの間の依存関係上の衝突を避け、システムワイドのアプ" +"リケーションとの間で同じ Python インタープリタを使う際の衝突を避けることがで" +"きます (特に Linux 環境で)。" -#: ../source/key_projects.rst:127 +#: ../source/guides/tool-recommendations.rst:43 msgid "" -"Flit uses ``pyproject.toml`` to configure a project. Flit does not rely on " -"tools such as :ref:`setuptools` to build distributions, or :ref:`twine` to " -"upload them to PyPI. Flit requires Python 3, but you can use it to " -"distribute modules for Python 2, so long as they can be imported on Python 3." +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." msgstr "" -"Flit は、 ``pyproject.toml`` を使ってプロジェクトの設定を行います。Flit は、" -"配布物をビルドする :ref:`setuptools` やそれを PyPI へアップロードする :ref:" -"`twine` のようなツールには依存していません。 Flit は Python 3 を要求します" -"が、Python 3 上にインポートできるものであれば Python 2 向けのモジュールでも配" -"布することが可能です。" +"特に科学計算ソフトウェア向けには :ref:`Conda` や :ref:`Spack` を検討してくだ" +"さい。" -#: ../source/key_projects.rst:132 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "ここか、新しい議論として、\"pip vs. Conda\" の比較を書くべし。" + +#: ../source/guides/tool-recommendations.rst:47 msgid "" -"The flit package is lifted by `Matthias Bussonnier `__ since October 2023 on the `tidelift platform `__, and funds sent to the PSF and earmarked for " -"PyPA usage." +"Do **not** use ``easy_install`` (part of :ref:`setuptools`), which is " +"deprecated in favor of pip (see :ref:`pip vs easy_install` for details). " +"Likewise, do **not** use ``python setup.py install`` or ``python setup.py " +"develop``, which are also deprecated (see :ref:`setup-py-deprecated` for " +"background and :ref:`modernize-setup-py-project` for migration advice)." msgstr "" -"flit パッケージは、2023年10月以来、 `tidelift platform `__ でリフト (訳註、維持管理に対して対価を払う" -"の意か) され、また、PSF に送られたファンドで PyPA 向けに使うように指定された" -"資金を使って、 `Matthias Bussonnier `__ によって" -"維持管理されています。" +"``easy_install`` (:ref:`setuptools` の一部) は、 pip の登場によって非推奨に" +"なっていますので、 **使わない** でください (詳しくは :ref:`pip vs " +"easy_install` を見てください)。同様に、 ``python setup.py install`` や " +"``python setup.py develop`` も非推奨になっていますので **使わない** でくださ" +"い (背景については :ref:`setup-py-deprecated` を、移行するためのアドバイスに" +"ついては :ref:`setup.py 近代化プロジェクト ` を見" +"てください)。" -#: ../source/key_projects.rst:142 -msgid "hatch" -msgstr "hatch" +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "ロックファイル" -#: ../source/key_projects.rst:144 +#: ../source/guides/tool-recommendations.rst:57 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +":ref:`pip-tools` and :ref:`Pipenv` are two recognized tools to create lock " +"files, which contain the exact versions of all packages installed into an " +"environment, for reproducibility purposes." msgstr "" -"`説明文書 `__ | `GitHub `__ | `PyPI `__" +":ref:`pip-tools` と :ref:`Pipenv` は、再現性を高める目的でロックファイル、そ" +"こにはその環境にインストールされたパッケージの正確なバージョンを含みますが、" +"そのようなロックファイルを作成するためのツールとしてよく知られています。" -#: ../source/key_projects.rst:148 +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "ビルドバックエンド" + +#: ../source/guides/tool-recommendations.rst:67 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 :term:`build backend ` Hatchling " -"to configure, version, specify dependencies for, and publish packages to " -"PyPI. Its plugin system allows for easily extending functionality." +"Please, remember: this document does not seek to steer the reader towards a " +"particular tool, only to enumerate common tools. Different use cases often " +"need specialized workflows." msgstr "" -"Hatch は、 Python での開発者向けに依存関係の管理や環境の分離を便利に行うため" -"の統合されたコマンドラインツールです。 Python パッケージ開発者は Hatch とそ" -"の :term:`ビルドバックエンド ` である Hatchling を使って、パッ" -"ケージの設定を実施し、バージョン管理を行い、依存関係を指定し、そして PyPI で" -"公開することができます。プラグインシステムがあるので、容易に機能を拡張するこ" -"とができます。" +"どうか覚えておいてください: このドキュメントは、読者に特定のツールへ向かって" +"舵を切らせることを追求しているわけではなく、一般的なツール群を列挙しているだ" +"けです。異なるユースケースでは、しばしば、そのケースに特化したワークフローが" +"必要になります。" -#: ../source/key_projects.rst:157 -msgid "packaging" -msgstr "packaging ライブラリ" +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" +"純 Python のパッケージを取り扱う :term:`ビルドバックエンド ` " +"で人気のあるものは、アルファベット順に:" -#: ../source/key_projects.rst:159 +#: ../source/guides/tool-recommendations.rst:74 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +":doc:`Flit-core ` -- developed with but separate from :" +"ref:`Flit`. A minimal and opinionated build backend. It does not support " +"plugins." msgstr "" -":doc:`説明文書 ` | `課題リスト `__ | `GitHub `__ | " -"`PyPI `__" +":doc:`Flit-core ` -- :ref:`Flit` とともに開発されたが別" +"のもの。最小限で自己主張の強いビルドバックエンド。プラグインをサポートしな" +"い。" -#: ../source/key_projects.rst:164 +#: ../source/guides/tool-recommendations.rst:77 msgid "" -"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." msgstr "" -"(packaging ライブラリには) :ref:`pip` や :ref:`setuptools` で使われる Python " -"パッケージングのための中核的なユーティリティ (としての core utilities があり" -"ます)。" +"Hatchling_ -- :ref:`Hatch` とともに開発されたが別のもの。プラグインをサポート" +"する。" -#: ../source/key_projects.rst:166 +#: ../source/guides/tool-recommendations.rst:79 msgid "" -"The core utilities in the packaging library handle version handling, " -"specifiers, markers, requirements, tags, and similar attributes and tasks " -"for Python packages. Most Python users rely on this library without needing " -"to explicitly call it; developers of the other Python packaging, " -"distribution, and installation tools listed here often use its functionality " -"to parse, discover, and otherwise handle dependency attributes." +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." msgstr "" -"packaging ライブラリの core utilities は、バージョンの取り扱い、識別子、マー" -"カ、依存先パッケージ、タグ、その他これに類似した属性やタスクを取り扱います。 " -"Python ユーザのほとんどは、明示的に呼び出す必要に迫られることはなくともこのラ" -"イブラリに依存しています; ここにリストされているような Python のパッケージン" -"グや配布やインストールを扱う他のパッケージを開発する者は、パースしたり検出し" -"たりそうでなければ依存関係の属性を取り扱うようなこのライブラリの機能をしばし" -"ば利用しています。" +"PDM-backend_ -- :ref:`PDM` とともに開発されたが別のもの。プラグインをサポー" +"ト。" -#: ../source/key_projects.rst:174 +#: ../source/guides/tool-recommendations.rst:81 msgid "" -"This project specifically focuses on implementing the modern Python " -"packaging interoperability standards defined at :ref:`packaging-" -"specifications`, and will report errors for sufficiently old legacy packages " -"that are incompatible with those standards. In contrast, the :ref:`distlib` " -"project is a more permissive library that attempts to provide a plausible " -"reading of ambiguous metadata in cases where :ref:`packaging` will instead " -"report on error." +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." msgstr "" -"このプロジェクトは、 :ref:`パッケージング仕様 `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +"Unlike other backends on this list, Poetry-core does not support the " +"standard :ref:`[project] table ` (it uses a " +"different format, in the ``[tool.poetry]`` table)." msgstr "" -"`説明文書 `__ | `課題リスト `__ | `GitHub `__ | `PyPI `__" +"このリストの他のバックエンドとは異なって、 Poetry-core は標準的な :ref:" +"`[project] table ` をサポートしていません (``[tool." +"poetry]`` テーブル内に別のフォーマットで書くことはできます)。" -#: ../source/key_projects.rst:193 +#: ../source/guides/tool-recommendations.rst:88 msgid "" -"The most popular tool for installing Python packages, and the one included " -"with modern versions of Python." +":ref:`setuptools`, which used to be the only build backend. Supports plugins." msgstr "" -"Python パッケージをインストールするに当たっての最もよく知られたツールで、" -"Python の新しめのバージョンには同梱されているもの。" +":ref:`setuptools` は、以前は唯一のビルドバックエンドでした。プラグインをサ" +"ポート。" -#: ../source/key_projects.rst:196 +#: ../source/guides/tool-recommendations.rst:92 msgid "" -"It provides the essential core features for finding, downloading, and " -"installing packages from PyPI and other Python package indexes, and can be " -"incorporated into a wide range of development workflows via its command-line " -"interface (CLI)." +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." msgstr "" -"PyPI やその他の Python パッケージインデックスのパッケージを探索・ダウンロー" -"ド・インストールするための基本的な機能を提供するとともに、コマンドラインイン" -"タフェイス (CLI) を通じて広範囲の開発ワークフローに組み込むことができます。" - -#: ../source/key_projects.rst:204 -msgid "Pipenv" -msgstr "Pipenv" +"setuptools を使うのであれば、標準化の努力が為される前の幾つかの機能が今では非" +"推奨になっていて互換性を保つために *一時的に継続使用* しているだけであること" +"を忘れないでください。" -#: ../source/key_projects.rst:206 +#: ../source/guides/tool-recommendations.rst:96 msgid "" -":doc:`Docs ` | `Source `__ | " -"`Issues `__ | `PyPI `__" +"In particular, do **not** use direct ``python setup.py`` invocations. On the " +"other hand, configuring setuptools with a :file:`setup.py` file is still " +"fully supported, although it is recommended to use the modern :ref:" +"`[project] table in pyproject.toml ` (or :file:" +"`setup.cfg`) whenever possible and keep :file:`setup.py` only if " +"programmatic configuration is needed. See :ref:`setup-py-deprecated`." msgstr "" -":doc:`説明文書 ` | `ソースコード `__ | `課題リスト `__ | `PyPI " -"`__" +"とりわけ、 ``python setup.py`` のように直接に起動しては *いけません* 。他方" +"で、可能であればいつでも近代的な :ref:`[project] table in pyproject.toml " +"` (または :file:`setup.cfg`) を使うことや、プログラム" +"的な設定が必要とされる場合にのみ :file:`setup.py` を使い続けることが推奨され" +"てはいますが、 :file:`setup.py` を使って setuptools に設定を渡すことは今も完" +"全にサポートされています。 :ref:`setup-py-deprecated` を見てください。" -#: ../source/key_projects.rst:211 +#: ../source/guides/tool-recommendations.rst:103 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 `_." +"Other examples of deprecated features you should **not** use include the " +"``setup_requires`` argument to ``setup()`` (use the :ref:`[build-system] " +"table ` in :file:`pyproject.toml` " +"instead), and the ``easy_install`` command (cf. :ref:`pip vs easy_install`)." msgstr "" -"Pipenv は、全てのパッケージング世界の最良のものを Python 世界に持ち込むことを" -"目的とするプロジェクトです。 :ref:`Pipfile` ・ :ref:`pip` ・ :ref:" -"`virtualenv` を単一のツールチェーンにまとめ上げるものです。 ``requirements." -"txt`` を自動的にインポートすることができ、また、 `safety `_ を使って `Pipfile`_ 中の CVE を確認することができます。" +"非推奨となった機能の他の例としては、 ``setup()`` の ``setup_requires`` 引数を" +"使うべきではなく (代わりに :file:`pyproject.toml` 内の :ref:`[build-system] " +"テーブル ` を使ってください) 、また、 " +"``easy_install`` コマンドを使うことも非推奨になっています (cf. :ref:`pip vs " +"easy_install`) 。" -#: ../source/key_projects.rst:216 +#: ../source/guides/tool-recommendations.rst:108 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 checks file hashes, to ensure compliance " -"with hash-locked dependency specifiers, and eases uninstallation of packages " -"and dependencies." +"Do **not** use :ref:`distutils`, which is deprecated, and has been removed " +"from the standard library in Python 3.12, although it still remains " +"available from setuptools." msgstr "" -"Pipenv は、ユーザがコマンドラインで環境・依存関係・インポートされたパッケージ" -"を管理することを補助することを目的としています。 (他のツールが往々にしてうま" -"く動かない) Windows 上でもきちんと動作し、ファイルのハッシュ値を計算し確認す" -"ることでハッシュ値による依存関係識別子との互換性を確保し、パッケージの依存関" -"係先のアンインストールを容易にします。" - -#: ../source/key_projects.rst:225 -msgid "Pipfile" -msgstr "Pipfile" - -#: ../source/key_projects.rst:227 -msgid "`Source `__" -msgstr "`ソースコード `__" +":ref:`distutils` を *使わないで* ください、というのも、これは非推奨になってい" +"ますし、まだ setuptools から利用可能ではありますが Python 3.12 で標準ライブラ" +"リから取り除かれたものです。" -#: ../source/key_projects.rst:229 +#: ../source/guides/tool-recommendations.rst:112 msgid "" -":file:`Pipfile` and its sister :file:`Pipfile.lock` are a higher-level " -"application-centric alternative to :ref:`pip`'s lower-level :file:" -"`requirements.txt` file." +"For packages with :term:`extension modules `, it is best " +"to use a build system with dedicated support for the language the extension " +"is written in, for example:" msgstr "" -":file:`Pipfile` とその姉妹 :file:`Pipfile.lock` は、 :ref:`pip` における低レ" -"ベルの :file:`requirements.txt` ファイルに代わる高レベルのアプリケーション中" -"心のファイルです。" - -#: ../source/key_projects.rst:236 -msgid "pipx" -msgstr "pipx" +":term:`拡張モジュール ` を伴うパッケージについては、その拡" +"張が書かれた言語用の専用サポートのあるビルドシステムを使うのが最善です、例え" +"ば:" -#: ../source/key_projects.rst:238 +#: ../source/guides/tool-recommendations.rst:116 msgid "" -"`Docs `__ | `GitHub `__ " -"| `PyPI `__" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," msgstr "" -"`説明文書 `__ | `GitHub `__ | `PyPI `__" +":ref:`setuptools` -- C 言語および C++ 言語をネイティブにサポート (サードパー" +"ティのプラグインで Go 言語と Rust 言語も)、" -#: ../source/key_projects.rst:242 +#: ../source/guides/tool-recommendations.rst:117 msgid "" -"pipx is a tool to install and run Python command-line applications without " -"causing dependency conflicts with other packages installed on the system." +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," msgstr "" -"pipx は、システムにインストール済みの他のパッケージとの間に依存関係の衝突を起" -"こすことなく Python のコマンドラインアプリケーションをインストールし動作させ" -"るためのツールです。" +":ref:`meson-python` -- C 言語・ C++ 言語・ Fortran ・ Rust およびその他の言語" +"が Meson によってサポートされています、" -#: ../source/key_projects.rst:249 +#: ../source/guides/tool-recommendations.rst:118 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," msgstr "" -":doc:`説明文書 ` | `課題リスト `__ | `GitHub `__" - -#: ../source/key_projects.rst:253 -msgid "This guide!" -msgstr "このガイド!" +":ref:`scikit-build-core` -- C 言語・ C++ 言語・ Fortran やその他の言語が " +"CMake によってサポートされています、" -#: ../source/key_projects.rst:258 -msgid "readme_renderer" -msgstr "readme_renderer" +#: ../source/guides/tool-recommendations.rst:119 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr ":ref:`maturin` -- Rust 、 Cargo を経由して。" -#: ../source/key_projects.rst:260 -msgid "" -"`GitHub and docs `__ | `PyPI " -"`__" -msgstr "" -"`GitHub および説明文書 `__ | `PyPI " -"`__" +#: ../source/guides/tool-recommendations.rst:123 +msgid "Building distributions" +msgstr "配布物をビルドする" -#: ../source/key_projects.rst:263 +#: ../source/guides/tool-recommendations.rst:125 msgid "" -"``readme_renderer`` is a library that package developers use to render their " -"user documentation (README) files into HTML from markup languages such as " -"Markdown or reStructuredText. Developers call it on its own or via :ref:" -"`twine`, as part of their release management process, to check that their " -"package descriptions will properly display on PyPI." -msgstr "" -"``readme_renderer`` は、Markdown や reStructuredText のようなマークアップ言語" -"で書かれたユーザ向け説明ファイル (README) を HTML に展開するためにパッケージ" -"開発者が用いるライブラリです。開発者は、リリース管理プロセスの一環として直接" -"または :ref:`twine` 経由でこれを呼び出し、そのパッケージに関する説明がきちん" -"と PyPI に表示されることを確認します。" - -#: ../source/key_projects.rst:274 -msgid "Setuptools" -msgstr "Setuptools" +"The standard tool to build :term:`source distributions ` and :term:`wheels ` for uploading to PyPI is :ref:" +"`build`. It will invoke whichever build backend you :ref:`declared " +"` in :file:`pyproject.toml`." +msgstr "" +"PyPI へアップロードするために :term:`ソースコード配布物 ` や :term:`wheels ` をビルドするための標準ツールは、 :" +"ref:`build` です。:file:`pyproject.toml` 内で `宣言された ` ビルドバックエンドが何であれ、それを起動することになりま" +"す。" -#: ../source/key_projects.rst:276 +#: ../source/guides/tool-recommendations.rst:130 msgid "" -"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +"Do **not** use ``python setup.py sdist`` and ``python setup.py bdist_wheel`` " +"for this task. All direct invocations of :file:`setup.py` are :ref:" +"`deprecated `." msgstr "" -"`説明文書 `__ | `課題リスト " -"`__ | `GitHub `__ | `PyPI `__" +"この作業のために ``python setup.py sdist`` や ``python setup.py " +"bdist_wheel`` を *使わないで* ください。:file:`setup.py` を直接に起動すること" +"は :ref:`非推奨 ` になっています。" -#: ../source/key_projects.rst:281 +#: ../source/guides/tool-recommendations.rst:134 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." +"If you have :term:`extension modules ` and want to " +"distribute wheels for multiple platforms, use :ref:`cibuildwheel` as part of " +"your CI setup to build distributable wheels." msgstr "" -"(``easy_install`` を含む) Setuptools は Python の distutils への拡張を集めた" -"もので、特に他のパッケージに依存関係がある場合に、より簡単に Python の :term:" -"`配布物 ` をビルドし配布することが可能となります。" +"もし、 :term:`拡張モジュール ` を使っていて複数のプラット" +"フォーム向けに wheel ファイルを配布したいと考えているなら、配布可能な wheel " +"ファイルをビルドする CI 環境の一部として :ref:`cibuildwheel` を使いましょう。" -#: ../source/key_projects.rst:289 -msgid "trove-classifiers" -msgstr "trove-classifiers" +#: ../source/guides/tool-recommendations.rst:140 +msgid "Uploading to PyPI" +msgstr "PyPIにアップロードする" -#: ../source/key_projects.rst:291 +#: ../source/guides/tool-recommendations.rst:142 msgid "" -"`Issues `__ | `GitHub " -"`__ | `PyPI `__" +"For projects hosted on GitHub, it is recommended to use the :ref:`trusted " +"publishing `, which allows the package to be securely " +"uploaded to PyPI from a GitHub Actions job. (This is not yet supported on " +"software forges other than GitHub.)" msgstr "" -"`課題リスト `__ | `GitHub " -"`__ | `PyPI `__" +"GitHubにホストされているプロジェクト向けには、GitHub Actions のジョブからパッ" +"ケージを安全に PyPIへアップロードすることができる :ref:`信頼ある出版 " +"` を使うことを推奨します。(これは、GitHub 以外のソフトウ" +"エア集積所ではまだサポートされていません。)" -#: ../source/key_projects.rst:295 +#: ../source/guides/tool-recommendations.rst:147 msgid "" -"trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to :ref:" -"`systematically describe their projects ` so that " -"users can better find projects that match their needs on the PyPI." +"The other available method is to upload the package manually using :ref:" +"`twine`." msgstr "" -"trove-classifiers は、`PyPI における分類子 `_ " -"の正統な源泉で、ユーザがそのニーズに即したプロジェクトを PyPI でよりうまく探" -"し出せるように、プロジェクトの保守者が `プロジェクトを体系的に表現する `_ のに使います。" +"利用可能なもうひとつの方法は、 :ref:`twine` を用いて手動でパッケージをアップ" +"ロードすることです。" -#: ../source/key_projects.rst:300 +#: ../source/guides/tool-recommendations.rst:149 msgid "" -"The trove-classifiers package contains a list of valid classifiers and " -"deprecated classifiers (which are paired with the classifiers that replace " -"them). Use this package to validate classifiers used in packages intended " -"for uploading to PyPI. As this list of classifiers is published as code, you " -"can install and import it, giving you a more convenient workflow compared to " -"referring to the `list published on PyPI `_. " -"The `issue tracker `_ for " -"the project hosts discussions on proposed classifiers and requests for new " -"classifiers." +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." msgstr "" -"trove-classifiers パッケージには、正当な分類子および (それを置き換えた分類子" -"と一組で) 非推奨になった分類子のリストが含まれています。 PyPI にアップロード" -"しようとしているパッケージで使われている分類子の正当性を確認するために、この" -"パッケージを使いましょう。この分類子リストがソースコードの形で公開されている" -"ので、それをインストールしてインポートすれば、 `PyPI で公開されているリスト " -"`_ を参照するよりももっと便利なワークフローを" -"構築することができます。本プロジェクトの `課題リスト `_ に、提案された分類子に関する議論や新しい分類" -"子が欲しいという要求に関する議論が公開されています。" +"このタスクを行うために ``python setup.py upload`` を使うことは *絶対にやめて" +"* ください。 :ref:`非推奨 ` であることに加えて、危険 " +" です。" -#: ../source/key_projects.rst:314 -msgid "twine" -msgstr "twine" +#: ../source/guides/tool-recommendations.rst:154 +msgid "Workflow tools" +msgstr "ワークフローツール" -#: ../source/key_projects.rst:316 +#: ../source/guides/tool-recommendations.rst:156 msgid "" -"`Docs `__ | `Issues `__ | `GitHub `__ | " -"`PyPI `__" +"These tools are environment managers that automatically manage virtual " +"environments for a project. They also act as \"task runners\", allowing you " +"to define and invoke tasks such as running tests, compiling documentation, " +"regenerating some files, etc. Some of them provide shortcuts for building " +"distributions and uploading to PyPI, and some support lock files for " +"applications. They often call the tools mentioned above under the hood. In " +"alphabetical order:" msgstr "" -"`説明文書 `__ | `課題リスト " -"`__ | `GitHub `__ | `PyPI `__" +"これらのツール群は、プロジェクトの仮想環境を自動的に管理する環境マネージャで" +"す。これらは、テストを走らせたり、説明文書をコンパイルしたり、何らかのファイ" +"ルを再生成したり、その他のタスクを定義して起動するための \"タスク実行係\" と" +"しても動作します。これらのうちのいくつかは配布物をビルドしたり PyPI にアップ" +"ロードするためのショートカットを提供しますし、あるいは、アプリケーション向け" +"のロックファイルをサポートしています。これらは、往々にして、先述のツール群を" +"内部的に呼び出しています。アルファベット順に:" -#: ../source/key_projects.rst:321 -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 " -"that passes program files and metadata to a web API. Developers use it " -"because it's the official PyPI upload tool, it's fast and secure, it's " -"maintained, and it reliably works." -msgstr "" -"Twine は、開発者がパッケージをPython パッケージインデックス (PyPI) や他の " -"Python 用パッケージインデックスへアップロードするのに使う最初の選択肢です。こ" -"れはコマンドラインプログラムで、プログラムのファイルやメタデータを web API へ" -"渡します。開発者がこれを使うのは、公式の PyPI へのアップロードツールであるか" -"らであり、動作が速く安全であるからであり、保守されているからであり、動作が信" -"頼できるからです。" +#: ../source/guides/tool-recommendations.rst:164 +msgid ":ref:`Flit`," +msgstr ":ref:`Flit`," -#: ../source/key_projects.rst:331 ../source/overview.rst:401 -msgid "virtualenv" -msgstr "virtualenv" +#: ../source/guides/tool-recommendations.rst:165 +msgid ":ref:`Hatch`," +msgstr ":ref:`Hatch`," -#: ../source/key_projects.rst:333 +#: ../source/guides/tool-recommendations.rst:166 +msgid ":doc:`nox `," +msgstr ":doc:`nox `," + +#: ../source/guides/tool-recommendations.rst:167 +msgid ":ref:`PDM`," +msgstr ":ref:`PDM`," + +#: ../source/guides/tool-recommendations.rst:168 +msgid ":ref:`Pipenv`," +msgstr ":ref:`Pipenv`," + +#: ../source/guides/tool-recommendations.rst:169 +msgid ":ref:`Poetry`," +msgstr ":ref:`Poetry`," + +#: ../source/guides/tool-recommendations.rst:170 +msgid ":doc:`tox `." +msgstr ":doc:`tox `." + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "``MANIFEST.in`` を使ってソースコード配布物にファイルを含める" + +#: ../source/guides/using-manifest-in.rst:7 msgid "" -"`Docs `__ | `Issues " -"`__ | `GitHub `__ | `PyPI `__" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." msgstr "" -"`説明文書 `__ | `課題リスト " -"`__ | `GitHub `__ | `PyPI `__" +"このページの情報は、setuptools 説明文書の中の :doc:`setuptools:userguide/" +"miscellaneous` に移されました。" -#: ../source/key_projects.rst:338 +#: ../source/guides/using-testpypi.rst:7 msgid "" -"virtualenv is a tool for creating isolated Python :term:`Virtual " -"Environments `, like :ref:`venv`. Unlike :ref:`venv`, " -"virtualenv can create virtual environments for other versions of Python, " -"which it locates using the PATH environment variable. It also provides " -"convenient features for configuring, maintaining, duplicating, and " -"troubleshooting virtual environments. For more information, see the section " -"on :ref:`Creating and using Virtual Environments`." +"``TestPyPI`` is a separate instance of the :term:`Python Package Index " +"(PyPI)` that allows you to try out the distribution tools and process " +"without worrying about affecting the real index. TestPyPI is hosted at `test." +"pypi.org `_" msgstr "" -"virtualenv は、 :ref:`venv` と同様に独立した Python :term:`仮想環境 ` を生成するツールです。 :ref:`venv` とは異なり、virtualenv は " -"PATH 環境変数を使って特定することで他のバージョンの Python 用の仮想環境を作成" -"することができます。他にも、仮想環境の設定・保守・複製・問題解決のための便利" -"な機能を提供しています。より詳しくは、 :ref:`仮想環境を作って使う ` の節を見てください。" +"``TestPyPI`` は :term:`Python パッケージインデックス ` とは別のインスタンスで、本番環境に影響を与えてしまう心配をせずに配布" +"ツールやプロセスを試してみることができます。 TestPyPI は `test.pypi.org " +"`_ にホストされています" -#: ../source/key_projects.rst:350 -msgid "Warehouse" -msgstr "Warehouse" +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "アカウントを登録する" -#: ../source/key_projects.rst:352 +#: ../source/guides/using-testpypi.rst:15 msgid "" -"`Docs `__ | `Issues `__ | `GitHub `__" +"Because TestPyPI has a separate database from the live PyPI, you'll need a " +"separate user account specifically for TestPyPI. Go to https://test.pypi.org/" +"account/register/ to register your account." msgstr "" -"`説明文書 `__ | `課題リスト `__ | `GitHub `__" +"TestPyPI は PyPI とは別のデータベースで運用されているので、 TestPyPI 専用の" +"ユーザアカウントを作成する必要があります。 https://test.pypi.org/account/" +"register/ へ行ってアカウントを登録しましょう。" -#: ../source/key_projects.rst:356 +#: ../source/guides/using-testpypi.rst:19 msgid "" -"The current codebase powering the :term:`Python Package Index (PyPI)`. It is " -"hosted at `pypi.org `_. The default source for :ref:`pip` " -"downloads." +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." msgstr "" -"現在の :term:`Python パッケージインデックス ` を" -"構成しているコードベース。 `pypi.org `_ にホストされていま" -"す。 :ref:`pip` がダウンロードする際のデフォルトのソースです。" - -#: ../source/key_projects.rst:364 -msgid "wheel" -msgstr "wheel" +"TestPyPI 用のデータベースは定期的に刈り込まれるので、往々にしてユーザアカウン" +"トが削除されることがあります。" -#: ../source/key_projects.rst:366 -msgid "" -"`Docs `__ | `Issues `__ | `GitHub `__ | " -"`PyPI `__" -msgstr "" -"`説明文書 `__ | `課題リスト " -"`__ | `GitHub `__ | `PyPI `__" +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "Twine を使って TestPyPI を使う" -#: ../source/key_projects.rst:371 +#: ../source/guides/using-testpypi.rst:26 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." +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" msgstr "" -"wheel は、主として :term:`wheel 配布物 ` を作成するための :ref:" -"`setuptools` の拡張である ``bidet_wheel`` を提供するプロジェクトです。この他" -"にも、wheel ファイルを作成しインストールするためのコマンドラインユーティリ" -"ティを提供します。" +":ref:`twine` に ``--repository`` フラグを指定して使うことで、配布物を " +"TestPyPI にアップロードすることができます:" -#: ../source/key_projects.rst:375 +#: ../source/guides/using-testpypi.rst:33 msgid "" -"See also `auditwheel `__, a tool that " -"package developers use to check and fix Python packages they are making in " -"the binary wheel format. It provides functionality to discover dependencies, " -"check metadata for compliance, and repair the wheel and metadata to properly " -"link and include external shared libraries in a package." +"You can see if your package has successfully uploaded by navigating to the " +"URL ``https://test.pypi.org/project/`` where " +"``sampleproject`` is the name of your project that you uploaded. It may take " +"a minute or two for your project to appear on the site." msgstr "" -"パッケージ開発者がバイナリの wheel フォーマットで開発中の Python パッケージを" -"チェックし問題を解決するためのツールである `auditwheel `__ も見てください。このツールは、依存関係を検出し、法令遵守" -"のためのメタデータを確認し、 wheel とメタデータがパッケージないの外部共有ライ" -"ブラリに正しくリンクしインクルードするように修正する機能を提供します。" - -#: ../source/key_projects.rst:384 -msgid "Non-PyPA Projects" -msgstr "非 PyPA プロジェクト" +"``https://test.pypi.org/project/`` の ``sample project`` の部" +"分をあなたがアップロードしたプロジェクトの名前に置き換えた URL を参照すれば、" +"あなたのパッケージがうまくアップロードできたかどうかを確認することができま" +"す。サイトにあなたのプロジェクトが反映されるまでには 1,2 分かかるかもしれませ" +"ん。" -#: ../source/key_projects.rst:389 -msgid "buildout" -msgstr "buildout" +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "pip で TestPyPI を使う" -#: ../source/key_projects.rst:391 +#: ../source/guides/using-testpypi.rst:41 msgid "" -"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" msgstr "" -"`説明文書 `__ | `課題リスト `__ | `PyPI `__ | `GitHub `__" +":ref:`pip` で PyPI の代わりに TestPyPI からパッケージをダウンロードするに" +"は、 ``--index-url`` フラグを指定しましょう:" -#: ../source/key_projects.rst:396 +#: ../source/guides/using-testpypi.rst:56 msgid "" -"Buildout is a Python-based build system for creating, assembling and " -"deploying applications from multiple parts, some of which may be non-Python-" -"based. It lets you create a buildout configuration and reproduce the same " -"software later." +"If you want to allow pip to also download packages from PyPI, you can " +"specify ``--extra-index-url`` to point to PyPI. This is useful when the " +"package you're testing has dependencies:" msgstr "" -"Buildout は Python ベースのビルドシステムで、非 Python ベースのものを含む複数" -"の部品から構成されるアプリケーションの生成・組み立て・配置ができます。" -"buildout の設定を作っておけば、後で同じソフトウェアを再生成することができま" -"す。" - -#: ../source/key_projects.rst:403 -msgid "conda" -msgstr "conda" +"pip が PyPI からもパッケージをダウンロードできるようにしたいのであれば、 ``--" +"extra-index-url`` に PyPI を指定しましょう。テストしようとしているパッケージ" +"が依存関係を持つ場合にこれが役に立ちます:" -#: ../source/key_projects.rst:405 -msgid ":doc:`Docs `" -msgstr ":doc:`説明文書 `" +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr ":file:`.pypirc` ファイルで TestPyPI を設定する" -#: ../source/key_projects.rst:407 +#: ../source/guides/using-testpypi.rst:75 msgid "" -"conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " -"from `Anaconda, Inc `__ " -"specifically aimed at the scientific community, and in particular on Windows " -"where the installation of binary extensions is often difficult." +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" -"conda は、 Python 実装である `Anaconda `__ のためのパッケージ管理ツールです。Anaconda Python は、 `Anaconda, Inc " -"`__ が特に科学計算の分野に向け" -"て配布している配布物で、とりわけ通常ならバイナリ拡張のインストールが難しいと" -"される Windows 用に配布しています。" +"ユーザ名やパスワードの入力を毎回促されるのを避けたいなら、 :file:`$HOME/." +"pypirc` 内で TestPyPI の設定をしておくことができます。" -#: ../source/key_projects.rst:414 +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "``pyproject.toml`` を書く" + +#: ../source/guides/writing-pyproject-toml.rst:7 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." +"``pyproject.toml`` is a configuration file used by packaging tools, as well " +"as other tools such as linters, type checkers, etc. There are three possible " +"TOML tables in this file." msgstr "" -"Conda は、 :ref:`pip` や virtualenv や wheel とは全く別のツールですが、パッ" -"ケージ管理・仮想環境管理・バイナリ拡張のデプロイメントの観点ではこれらのツー" -"ルを合わせたような機能を提供します。" +"``pyproject.toml`` は、lintersやtype checkersやその他のパッケージングツール群" +"でも同様に使われる設定ファイルです。このファイルの中には３個の TOML テーブル" +"を置くことが可能です。" -#: ../source/key_projects.rst:418 +#: ../source/guides/writing-pyproject-toml.rst:11 msgid "" -"Conda does not install packages from PyPI and can install only from the " -"official Anaconda repositories, or anaconda.org (a place for user-" -"contributed *conda* packages), or a local (e.g. intranet) package server. " -"However, note that :ref:`pip` can be installed into, and work side-by-side " -"with conda for managing :term:`distributions ` from " -"PyPI. Also, `conda skeleton `__ is a tool to make " -"Python packages installable by conda by first fetching them from PyPI and " -"modifying their metadata." +"The ``[build-system]`` table is **strongly recommended**. It allows you to " +"declare which :term:`build backend` you use and which other dependencies are " +"needed to build your project." msgstr "" -"Conda は PyPI からパッケージをインストールすることはなく、公式の Anaconda リ" -"ポジトリか、anaconda.org (ユーザが貢献した *conda* パッケージの置き場所) か、" -"または、ローカル (例えばイントラネット) にあるパッケージサーバからのみインス" -"トールすることができます。しかしながら、:ref:`pip` をインストールすることは可" -"能で、PyPI からの :term:`配布物 ` の管理という点では " -"conda と平行して動作することができます。また、 `conda skeleton `__ は、 PyPI から持ってきた Python パッケージのメタデータを修" -"正することで conda がインストールできるものにするためのツールです。" - -#: ../source/key_projects.rst:431 -msgid "devpi" -msgstr "devpi" +"``[build-system]`` テーブルは、 **強く推奨されています** 。これを使うことで、" +"どの :term:`ビルドバックエンド ` を使うのか、また、そのプロ" +"ジェクトをビルドするためには他のどんな依存関係が必要なのかを宣言することがで" +"きます。" -#: ../source/key_projects.rst:433 +#: ../source/guides/writing-pyproject-toml.rst:15 msgid "" -"`Docs `__ | :gh:`Issues ` " -"| `PyPI `__" +"The ``[project]`` table is the format that most build backends use to " +"specify your project's basic metadata, such as the dependencies, your name, " +"etc." msgstr "" -"`説明文書 `__ | :gh:`課題リスト ` | `PyPI `__" +"``[project]`` テーブルは、依存関係や作者の名前など、そのプロジェクトの基本的" +"なメタデータを指定するためにほとんどのビルドバックエンドが用いるものです。" -#: ../source/key_projects.rst:437 +#: ../source/guides/writing-pyproject-toml.rst:18 msgid "" -"devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " -"complementary command line tool to drive packaging, testing and release " -"activities with Python. devpi also provides a browsable and searchable web " -"interface. devpi supports mirroring PyPI, multiple :term:`package indexes " -"` with inheritance, syncing between these indexes, index " -"replication and fail-over, and package upload." +"The ``[tool]`` table has tool-specific subtables, e.g., ``[tool.hatch]``, " +"``[tool.black]``, ``[tool.mypy]``. We only touch upon this table here " +"because its contents are defined by each tool. Consult the particular tool's " +"documentation to know what it can contain." msgstr "" -"devpi は、 PyPI 互換の強力なサーバと PyPI プロクシキャッシュの機能を持ってい" -"て、 Python を使ったパッケージングやテスティングやリリース活動を推進するため" -"の補完的なコマンドラインツールを備えています。devpi は、また、閲覧と検索が可" -"能なwebインタフェイスも備えています。devpi は、 PyPI のミラーを作成する機能、" -"継承関係を持った複数の :term:`パッケージインデックス ` を扱う" -"機能、これらのインデックスの間の同期機能、インデックスの複製とフェイルオーバ" -"とパッケージのアップロードの機能を提供できます。" +"``[tool]`` テーブルは、例えば ``[tool.hatch]`` や ``[tool.black]`` や " +"``[tool.mypy]`` のような、ツールに特化したサブテーブルを持っています。テーブ" +"ルの内容がツール毎に定義されているので、ここでは簡単に触れるだけに留めます。" +"何を含めておくことができるのかを知るためには、それぞれのツールの説明文書に当" +"たってみてください。" -#: ../source/key_projects.rst:448 -msgid "dumb-pypi" -msgstr "dumb-pypi" +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"There is a significant difference between the ``[build-system]`` and " +"``[project]`` tables. The former should always be present, regardless of " +"which build backend you use (since it *defines* the tool you use). The " +"latter is understood by *most* build backends, but some build backends use a " +"different format." +msgstr "" +"``[build-system]`` と ``[project]`` の二つのテーブルの間には、大きな差異があ" +"ります。どんなビルドバックエンドを使うのかに関わりなく前者は常に存在していな" +"ければなりません (というのも、どのツールを使うのかをこのテーブルで定義するか" +"らです)。後者は、 *ほとんどの* ビルドバックエンドが理解しますが、一部のバック" +"エンドは異なったフォーマットのものを用います。" -#: ../source/key_projects.rst:450 +#: ../source/guides/writing-pyproject-toml.rst:31 msgid "" -"`GitHub `__ | `PyPI `__" +"At the time of writing this (November 2023), Poetry_ is a notable build " +"backend that does not use the ``[project]`` table (it uses the ``[tool." +"poetry]`` table instead)." msgstr "" -"`GitHub `__ | `PyPI `__" +"これを書いている時点 (2023年11月) では、 ``[project]`` テーブルを使わないビル" +"ドバックエンドとしては、 Poetry_ が有名です (代わりに ``[tool.poetry]`` テー" +"ブルを使います) 。" -#: ../source/key_projects.rst:453 +#: ../source/guides/writing-pyproject-toml.rst:35 msgid "" -"dumb-pypi is a simple :term:`package index ` static file site " -"generator, which then must be hosted by a static file webserver to become " -"the package index. It supports serving the hash, core-metadata, and yank-" -"status." +"Also, the setuptools_ build backend supports both the ``[project]`` table, " +"and the older format in ``setup.cfg`` or ``setup.py``. For new projects, it " +"is recommended to use the ``[project]`` table, and keep ``setup.py`` only if " +"some programmatic configuration is needed (such as building C extensions), " +"but the ``setup.cfg`` and ``setup.py`` formats are still valid. See :ref:" +"`setup-py-deprecated`." msgstr "" -"dumb-pypi は簡潔な :term:`パッケージインデックス ` の静的ファ" -"イルのサイトを構築するツールで、パッケージインデックスとして機能するためには" -"静的ファイルをサポートするウェブサーバにホストされていなければなりません。" -"ハッシュ、コアとなるメタデータ、そして yank ステータスをサポートしています。" +"また、setuptools_ のビルドバックエンドは、 ``[project]`` テーブルと ``setup." +"cfg`` ないし ``setup.py`` の中のより古い形の両方をサポートしています。新しく" +"始めるプロジェクトでは ``[project]`` テーブルを使用し、 (C 言語拡張をビルドす" +"る場合のような) 何かプログラム面での設定が必要とされる場合に限って ``setup." +"py`` を使い続けることが推奨されていますが、依然として ``setup.cfg`` と " +"``setup.py`` の形式は正当なものです。 :ref:`setup-py-deprecated` をご覧くださ" +"い。" -#: ../source/key_projects.rst:460 -msgid "enscons" -msgstr "enscons" +#: ../source/guides/writing-pyproject-toml.rst:46 +msgid "Declaring the build backend" +msgstr "ビルドバックエンドを宣言する" -#: ../source/key_projects.rst:462 +#: ../source/guides/writing-pyproject-toml.rst:48 msgid "" -":gh:`Source ` | :gh:`Issues ` | `PyPI " -"`__" +"The ``[build-system]`` table contains a ``build-backend`` key, which " +"specifies the build backend to be used. It also contains a ``requires`` key, " +"which is a list of dependencies needed to build the project -- this is " +"typically just the build backend package, but it may also contain additional " +"dependencies. You can also constrain the versions, e.g., ``requires = " +"[\"setuptools >= 61.0\"]``." msgstr "" -":gh:`ソースコード ` | :gh:`課題リスト ` | `PyPI `__" +"``[build-system]`` テーブルは、使用されるべきビルドバックエンドを指定する " +"``build-backend`` キーを含んでいます。また、 プロジェクトをビルドするのに必要" +"な依存関係のリストである ``requires`` キーも含んでいます -- これは典型的には" +"ビルドバクエンドのパッケージだけですが、追加の依存関係を含んでいてもかまいま" +"せん。さらに、例えば ``requires = [\"setuptools >= 61.0\"]`` のようにバージョ" +"ンを制限することもできます。" -#: ../source/key_projects.rst:466 +#: ../source/guides/writing-pyproject-toml.rst:54 msgid "" -"Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" -"compatible source distributions and wheels without using distutils or " -"setuptools, including distributions with C extensions. Enscons has a " -"different architecture and philosophy than :ref:`distutils`. Rather than " -"adding build features to a Python packaging system, enscons adds Python " -"packaging to a general purpose build system. Enscons helps you to build " -"sdists that can be automatically built by :ref:`pip`, and wheels that are " -"independent of enscons." +"Usually, you'll just copy what your build backend's documentation suggests " +"(after :ref:`choosing your build backend `). Here " +"are the values for some common build backends:" msgstr "" -"Enscons は、 `SCons`_ に基礎を置く Python パッケージングツールです。 C 言語拡" -"張を含む配布物であっても distutils や setuptools を使うことなく :ref:`pip` 互" -"換のソースコード配布物や wheel をビルドすることができます。 Enscons の構造と" -"哲学は :ref:`distutils` のものとは異なります。 Python パッケージングシステム" -"にビルド機能を追加するのではなく、 enscons では汎用のビルドシステムに Python " -"パッケージング機能を追加しています。 Enscons は、 :ref:`pip` で自動的にビルド" -"された sdist や、enscons から独立した wheel をビルドすることを支援します。" +"通常は、ビルドバックエンドの説明文書が (:ref:`ビルドバックエンドを選択する " +"`) 示唆するものをコピーするだけでしょう。よく知られた" +"バックエンドでの値をいくつか挙げておきます:" -#: ../source/key_projects.rst:481 -msgid "Flask-Pypi-Proxy" -msgstr "Flask-Pypi-Proxy" +#: ../source/guides/writing-pyproject-toml.rst:93 +msgid "Static vs. dynamic metadata" +msgstr "静的なメタデータと動的なメタデータ" -#: ../source/key_projects.rst:483 +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "このガイド文書の残りの部分は、``[project]`` テーブルに捧げます。" + +#: ../source/guides/writing-pyproject-toml.rst:97 msgid "" -"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +"Most of the time, you will directly write the value of a ``[project]`` " +"field. For example: ``requires-python = \">= 3.8\"``, or ``version = " +"\"1.0\"``." msgstr "" -"`説明文書 `__ | :gh:`GitHub " -"` | `PyPI `__" +"ほとんどの場合、 ``[project]`` フィールドに直接に値を書き込むことになるでしょ" +"う。例えば: ``requires-python = \">= 3.8\"`` や ``version = \"1.0\"`` などで" +"す。" -#: ../source/key_projects.rst:487 ../source/key_projects.rst:681 -#: ../source/key_projects.rst:740 -msgid "Not maintained, project archived" -msgstr "もはや保守されておらず、アーカイブされたプロジェクト" +#: ../source/guides/writing-pyproject-toml.rst:101 +msgid "" +"However, in some cases, it is useful to let your build backend compute the " +"metadata for you. For example: many build backends can read the version from " +"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 "" +"しかしながら、ビルドバックエンドにメタデータを計算させる方が役に立つ場合もあ" +"ります。例えば: 多くのビルドバックエンドがソースコードや Git タグやその他似た" +"ようなものの中にある ``__version__`` 要素を読み取ることができます。そのような" +"場合には、以下の例のような方法を使ってそのフィールドを動的なものにしておくべ" +"きです、" -#: ../source/key_projects.rst:489 +#: ../source/guides/writing-pyproject-toml.rst:112 msgid "" -"Flask-Pypi-Proxy is a :term:`package index ` as a cached " -"proxy for PyPI." +"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 "" -"Flask-PyPI-Proxy は PyPI に対するキャッシュ付きのプロクシという形の :term:`" -"パッケージインデックス ` です。" +"フィールドが動的となっている場合、そこを埋めるのはビルドバックエンドの責任で" +"す。どうすれば良いのかについては、ビルドバックエンドの説明文書に当たってみて" +"ください。" -#: ../source/key_projects.rst:495 -msgid "Hashdist" -msgstr "Hashdist" +#: ../source/guides/writing-pyproject-toml.rst:118 +msgid "Basic information" +msgstr "基本的な情報" -#: ../source/key_projects.rst:497 +#: ../source/guides/writing-pyproject-toml.rst:123 +#: ../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:125 msgid "" -"`Docs `__ | `GitHub `__" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." msgstr "" -"`説明文書 `__ | `GitHub `__" +"PyPI 上でのプロジェクト名称を書いてください。このフィールドは必須のもので、動" +"的であるとマークできない唯一のフィールドです。" -#: ../source/key_projects.rst:500 +#: ../source/guides/writing-pyproject-toml.rst:133 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 " -"doesn’t work”. The best way for Pythonistas to think about Hashdist may be a " -"more powerful hybrid of :ref:`virtualenv` and :ref:`buildout`. It is aimed " -"at solving the problem of installing scientific software, and making package " -"distribution stateless, cached, and branchable. It is used by some " -"researchers but has been lacking in maintenance since 2016." +"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 "" -"Hashdist は、非特権ユーザソフトウェアの配布物をビルドするためのライブラリで" -"す。 Hashdist は、「Debian 技術が動作していない場合の Debian のような選択肢」" -"になろうとしています。 Python 支持者 (Pythonista) にとっては、 :ref:" -"`virtualenv` と :ref:`buildout` のより強力な混合物が Hashdist だと考えるのが" -"一番でしょう。科学計算分野のソフトウェアをインストールする際の問題を解決し、" -"パッケージ配布物をステートレスでキャッシュ可能かつ分岐可能にすることを目指し" -"ています。一部の研究者が使っていますが、2016 年以降は保守されていません。" - -#: ../source/key_projects.rst:512 -msgid "Maturin" -msgstr "Maturin" +"プロジェクトの名称は、ASCII文字・数字・アンダースコア \"``_``\"・ハイフン " +"\"``-``\"・ピリオド \"``.``\" だけでできていなければなりません。また、アン" +"ダースコア・ハイフン・ピリオドで始まってはなりません。" -#: ../source/key_projects.rst:514 +#: ../source/guides/writing-pyproject-toml.rst:137 msgid "" -"`Docs `__ | `GitHub `__" +"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 "" -"`説明文書 `__ | `GitHub `__" +"プロジェクト名の比較では、大文字小文字を区別せず、また、アンダースコア・ハイ" +"フン・ピリオドは何文字連続していても同じものとして扱います。例えば、あなたが " +"``cool-stuff`` という名前のプロジェクトを登録したなら、利用者がダウンロードし" +"たり依存関係を宣言したりするのに、次に挙げる綴りのいずれであっても使うことが" +"できます: ``Cool-Stuff`` ・ ``cool.stuff`` ・ ``COOL_STUFF`` ・ ``CoOl__-.-" +"__sTuFF`` 。" -#: ../source/key_projects.rst:517 -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." +#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" msgstr "" -"Maturin は Rust 拡張モジュール用のビルドバックエンドで、Rust で書かれていま" -"す。Windows ・ Linux ・ macOS および FreeBSD 上で python 3.7+ の wheel をビル" -"ドすることができ、それを PyPI にアップロードすることができ、また、 PyPy と " -"GraalPy に対する基本的なサポートもあります。" -#: ../source/key_projects.rst:525 -msgid "meson-python" -msgstr "meson-python" +#: ../source/guides/writing-pyproject-toml.rst:147 +msgid "Put the version of your project." +msgstr "プロジェクトのバージョンを書いてください。" -#: ../source/key_projects.rst:527 +#: ../source/guides/writing-pyproject-toml.rst:154 msgid "" -"`Docs `__ | `GitHub `__" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." msgstr "" -"`説明文書 `__ | `GitHub " -"`__" +"(アルファ版のリリース用の) ``2020.0.0a1`` のようなもっと込み入ったバージョン" +"指定子も可能ですので、 詳細については :ref:`仕様 ` を見て" +"ください。" -#: ../source/key_projects.rst:530 +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" +"動的であるとマークされることがしばしばではありますが、このフィールドは必須の" +"ものです" + +#: ../source/guides/writing-pyproject-toml.rst:165 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 " -"package. It supports a wide variety of languages, including C, and is able " -"to fill the needs of most complex build configurations." +"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 "" -"``meson-python`` は、 Meson_ ビルドシステムを使うビルドバックエンドです。これ" -"によって、 Python パッケージの作者が自分のパッケージ向けに Meson_ をビルドシ" -"ステムとして使うことを可能にします。これは C 言語を含む広範囲の言語をサポート" -"しており、最も複雑なビルド設定を記述することが可能になります。" +"これによって、 ``__version__`` 要素や Git のタグからバージョンを取得するよう" +"な使い方が可能になります。 :ref:`バージョンを１箇所で管理する ` を見てみてください。" -#: ../source/key_projects.rst:540 -msgid "multibuild" -msgstr "multibuild" +#: ../source/guides/writing-pyproject-toml.rst:171 +msgid "Dependencies and requirements" +msgstr "依存関係と要求事項" -#: ../source/key_projects.rst:542 -msgid "`GitHub `__" -msgstr "`GitHub `__" +#: ../source/guides/writing-pyproject-toml.rst:174 +#: ../source/specifications/pyproject-toml.rst:354 +msgid "``dependencies``/``optional-dependencies``" +msgstr "``dependencies``/``optional-dependencies``" -#: ../source/key_projects.rst:544 +#: ../source/guides/writing-pyproject-toml.rst:176 +msgid "If your project has dependencies, list them like this:" +msgstr "もしプロジェクトに依存関係があるなら、このように列挙してください:" + +#: ../source/guides/writing-pyproject-toml.rst:188 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`." +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." msgstr "" -"Multibuild は、Linux ・ macOS 向けや (柔軟性は落ちるが) Windows 向けの " -"Python :term:`wheels ` をビルドしテストする一揃いの CI スクリプトで" -"す。 :ref:`cibuildwheel` も見てください。" - -#: ../source/key_projects.rst:550 -msgid "nginx_pypi_cache" -msgstr "nginx_pypi_cache" +"バージョンに制限をかけるために使えるあらゆるシンタックスについては、 :ref:`依" +"存関係指定子 ` を参照してください。" -#: ../source/key_projects.rst:552 -msgid ":gh:`GitHub `" -msgstr ":gh:`GitHub `" +#: ../source/guides/writing-pyproject-toml.rst:191 +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 "" +"パッケージの特定の機能にのみ必要なものであれば、依存関係のうちのいくつかをオ" +"プションにしたい時があるかもしれません。そのような場合には、 ``optional-" +"dependencies`` に置きましょう。" -#: ../source/key_projects.rst:554 +#: ../source/guides/writing-pyproject-toml.rst:204 msgid "" -"nginx_pypi_cache is a :term:`package index ` caching proxy " -"using `nginx `_." +"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 "" -"nginx_pypi_cache は、 `nginx `_ を用いた :term:`パッ" -"ケージインデックス ` のキャッシュ機能付きプロクシです。" +"キーのぞれぞれが \"余分のパッケージング \" を定義します。上" +"の例では、プロジェクトを例えば GUI サポート付きでインストールするためには " +"``pip install your-project-name[gui]`` を使うことができます。" -#: ../source/key_projects.rst:560 -msgid "pdm" -msgstr "pdm" +#: ../source/guides/writing-pyproject-toml.rst:213 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 +msgid "``requires-python``" +msgstr "``requires-python``" -#: ../source/key_projects.rst:562 +#: ../source/guides/writing-pyproject-toml.rst:215 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." msgstr "" -"`説明文書 `__ | `GitHub `__ | `PyPI `__" +"これによってサポートされている Python の上限のバージョンを宣言することができ" +"ます [#requires-python-upper-bounds]_ 。" -#: ../source/key_projects.rst:566 +#: ../source/guides/writing-pyproject-toml.rst:227 +msgid "Creating executable scripts" +msgstr "実行可能なスクリプトを作成する" + +#: ../source/guides/writing-pyproject-toml.rst:229 msgid "" -"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " -"store project metadata as defined in :pep:`621`." +"To install a command as part of your package, declare it in the ``[project." +"scripts]`` table." msgstr "" -"PDM は近代的な Python パッケージ管理ソフトです。 :pep:`621` で定義されている" -"形でプロジェクトのメタデータを :term:`pyproject.toml` に保存します。" +"パッケージの一部としてコマンドをインストールするためには、 ``[project." +"scripts]`` テーブルで宣言してください。" -#: ../source/key_projects.rst:574 +#: ../source/guides/writing-pyproject-toml.rst:237 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"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 "" -"`説明文書 `__ | `GitHub `__ | `PyPI `__" +"この例では、プロジェクトをインストールした後に ``spam-cli`` コマンドが利用で" +"きるようになるでしょう。このコマンドを実行することで、 ``from spam import " +"main_cli; main_cli()`` と同等のことを行うでしょう。" -#: ../source/key_projects.rst:578 +#: ../source/guides/writing-pyproject-toml.rst:241 msgid "" -"Pex is a tool for generating :file:`.pex` (Python EXecutable) files, " -"standalone Python environments in the spirit of :ref:`virtualenv`. PEX files " -"are :doc:`zipapps ` that make deployment of Python " -"applications as simple as ``cp``. A single PEX file can support multiple " -"target platforms and can be created from standard :ref:`pip`-resolvable " -"requirements, a lockfile generated with ``pex3 lock ...`` or even another " -"PEX. PEX files can optionally have tools embedded that support turning the " -"PEX file into a standard venv, graphing dependencies and more." +"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 "" -"Pex は、 :ref:`virtualenv` を使った独立した Python 環境をに表現した :file:`." -"pex` (Python EXecutable) ファイルを生成するためのツールです。 PEX ファイル" -"は、 ``cp`` のような単純な Python アプリケーションをデプロイする :doc:" -"`zipapps ` です。単独の PEX ファイルで複数のターゲット" -"プラットフォームをサポートすることができ、標準の :ref:`pip` で解決できる要求" -"事項、つまり ``pex3 lock ...`` で生成されるロックファイルや別の PEX からで" -"あっても作成することができます。 PEX ファイルは、オプションとして PEX ファイ" -"ルを標準の venv に変換したり依存関係をグラフ化したり、あるいはもっと多くをサ" -"ポートするツールを内蔵することもできます。" - -#: ../source/key_projects.rst:590 -msgid "pip-tools" -msgstr "pip-tools" +"Windows では、このやり方でパッケージされたスクリプト群はターミナルを必要とし" +"ますので、グラフィカルなアプリケーションの内部から起動した場合にはターミナル" +"がポップアップすることでしょう。これが起きないようにするためには、 " +"``[project.scripts]`` の代わりに ``[project.gui-scripts]`` テープルを使ってく" +"ださい。" -#: ../source/key_projects.rst:592 +#: ../source/guides/writing-pyproject-toml.rst:251 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." msgstr "" -"`説明文書 `__ | `GitHub " -"`__ | `PyPI `__" +"そうすることで、コマンドラインからスクリプトを起動してスクリプトがバックグラ" +"ウンドで走らせることですぐに制御を取り戻すことができるでしょう。" -#: ../source/key_projects.rst:596 +#: ../source/guides/writing-pyproject-toml.rst:254 msgid "" -"pip-tools is a suite of tools meant for Python system administrators and " -"release managers who particularly want to keep their builds deterministic " -"yet stay up to date with new versions of their dependencies. Users can " -"specify particular release of their dependencies via hash, conveniently make " -"a properly formatted list of requirements from information in other parts of " -"their program, update all dependencies (a feature :ref:`pip` currently does " -"not provide), and create layers of constraints for the program to obey." +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." msgstr "" -"pip-tools は、Python システムの管理者やリリースマネージャで、特にビルドが必ず" -"できるように保ちたいけれども依存先の新バージョンに追随して最新の状態にもして" -"おきたいという人々のための一揃いのツール群です。ユーザはハッシュ値を与えるこ" -"とで依存先の特定のリリースを指定することや、そのプログラムの他の部分にある情" -"報から適切な書式の requirements を簡単に作成すること、すべての依存先を更新す" -"ること (これは現時点の :ref:`pip` にはない機能です) 、プログラムが従うべき制" -"約条件の層を作成することができます。" +"Windows 上では、 ``[project.scripts]`` と ``[project.gui-scripts]`` の間の差" +"異だけが実質的に効果を持ちます。" -#: ../source/key_projects.rst:608 -msgid "pip2pi" -msgstr "pip2pi" +#: ../source/guides/writing-pyproject-toml.rst:260 +msgid "About your project" +msgstr "あなたのプロジェクトについて" -#: ../source/key_projects.rst:610 +#: ../source/guides/writing-pyproject-toml.rst:263 +#: ../source/specifications/pyproject-toml.rst:251 +msgid "``authors``/``maintainers``" +msgstr "``authors``/``maintainers``" + +#: ../source/guides/writing-pyproject-toml.rst:265 msgid "" -":gh:`GitHub ` | `PyPI `__" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." msgstr "" -":gh:`GitHub ` | `PyPI `__" +"これらのフィールドは両方とも名前とメールアドレスの両方またはいずれかで識別さ" +"れる人々のリストを含みます。" -#: ../source/key_projects.rst:613 +#: ../source/guides/writing-pyproject-toml.rst:285 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "``説明 ``" + +#: ../source/guides/writing-pyproject-toml.rst:287 msgid "" -"pip2pi is a :term:`package index ` server where specific " -"packages are manually synchronised." +"This should be a one-line description of your project, to show as the " +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -"pip2pi は、特定のパッケージ群が手動で同期される :term:`パッケージインデック" -"ス ` です。" +"これは、PyPI におけるプロジェクトページの \"ヘッドライン\" (`例 `_) や検索結果 (`例 `_) のような他の場所で表示されるも" +"のなので、１行でプロジェクトの説明をしたものであるべきです。" -#: ../source/key_projects.rst:619 -msgid "piwheels" -msgstr "piwheels" +#: ../source/guides/writing-pyproject-toml.rst:298 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 +msgid "``readme``" +msgstr "``readme``" -#: ../source/key_projects.rst:621 +#: ../source/guides/writing-pyproject-toml.rst:300 msgid "" -"`Website `__ | :doc:`Docs ` | " -"`GitHub `__" +"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 "" -"`Web サイト `__ | :doc:`説明文書 ` | `GitHub `__" +"これはプロジェクトの長めの説明文で、PyPI のプロジェクトページに表示されます。" +"典型的には、プロジェクトには ``README.md`` か ``README.rst`` のファイルが存在" +"するものなので、その場合にはここにはそのファイル名だけを書いておけば良いで" +"しょう。" -#: ../source/key_projects.rst:625 +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "The README's format is auto-detected from the extension:" +msgstr "README のフォーマットは拡張から自動的に検出されます:" + +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "``README.md`` → `GitHub 流のマークダウン `_ 、" + +#: ../source/guides/writing-pyproject-toml.rst:312 msgid "" -"piwheels is a website, and software underpinning it, that fetches source " -"code distribution packages from PyPI and compiles them into binary wheels " -"that are optimized for installation onto Raspberry Pi computers. Raspberry " -"Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -"piwheels は、ソースコード配布物パッケージを PyPI から取得して Raspberry Pi 計" -"算機へのインストールに最適化されたバイナリ wheel ファイルにコンパイルするよう" -"な Web サイトであり、それを支えるソフトウェアです。 Raspberry Pi OS では、 " -"pip が PyPI に加えて piwheel.org を追加のインデックスとして使うように予め設定" -"されています。" +"``README.rst`` → `reStructuredText _`_ (ただし Sphinx 拡張なし)。" -#: ../source/key_projects.rst:634 -msgid "poetry" -msgstr "poetry" +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "You can also specify the format explicitly, like this:" +msgstr "次のようにしてフォーマットを明示的に指定することもできます:" -#: ../source/key_projects.rst:636 +#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "``ライセンス``" + +#: ../source/guides/writing-pyproject-toml.rst:327 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"This can take two forms. You can put your license in a file, typically " +"``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -"`説明文書 `__ | `GitHub `__ | `PyPI `__" +"これは、ふたつの形式を採ります。典型的には ``LICENSE`` か ``LICENSE.txt`` と" +"いうファイル名でライセンスをファイルとして置いておいて、ここにはそのファイル" +"へのリンクを書いて置くこともできます:" -#: ../source/key_projects.rst:640 +#: ../source/guides/writing-pyproject-toml.rst:335 +msgid "or you can write the name of the license:" +msgstr "あるいは、ライセンスの名称を書いておくことも可能です:" + +#: ../source/guides/writing-pyproject-toml.rst:342 msgid "" -"poetry is a command-line tool to handle dependency installation and " -"isolation as well as building and packaging of Python packages. It uses " -"``pyproject.toml`` and, instead of depending on the resolver functionality " -"within :ref:`pip`, provides its own dependency resolver. It attempts to " -"speed users' experience of installation and dependency resolution by locally " -"caching metadata about dependencies." +"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 "" -"poetry は、 Python パッケージのビルドやパッケージングに加えて、依存先のインス" -"トールや隔離を取り扱うコマンドラインのツールです。 :ref:`pip` に含まれる解決" -"機能に依存する代わりに ``pyproject.toml`` を使って自分自身の依存関係解決機能" -"を提供します。依存関係に関するメタデータをローカルにキャッシュすることでイン" -"ストールや依存関係解決のユーザ体験を高速化しようとしています。" +"標準的でよく知られたライセンスを使うのであれば、このフィールドを使う必要はあ" +"りません。代わりに、 ``License::`` で始まる :ref:`分類子 ` のう" +"ちのひとつを書いておけば良いでしょう。 (一般的な規則としては標準的でよく知ら" +"れたライセンスを使うことは良い考えです、というのは、混乱を避けるとことにもな" +"るし、中には内部で認可済みのライセンスでなければソフトウェアを使えない組織も" +"あるからです。)" -#: ../source/key_projects.rst:650 -msgid "proxpi" -msgstr "proxpi" +#: ../source/guides/writing-pyproject-toml.rst:350 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "``keywords``" -#: ../source/key_projects.rst:652 +#: ../source/guides/writing-pyproject-toml.rst:352 msgid "" -":gh:`GitHub ` | `PyPI `__" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." msgstr "" -":gh:`GitHub ` | `PyPI `__" +"これは、 PyPI 上の検索でキーワードが与えられた時にこのプロジェクトをサジェス" +"トするのを助けます。" -#: ../source/key_projects.rst:655 +#: ../source/guides/writing-pyproject-toml.rst:364 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "``分類詞 ``" + +#: ../source/guides/writing-pyproject-toml.rst:366 msgid "" -"proxpi is a simple :term:`package index ` which proxies PyPI " -"and other indexes with caching." +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." msgstr "" -"proxpi は、PyPI や他のインデックスをキャッシュ付きでプロクシする単純な :term:" -"`パッケージインデックス ` です。" - -#: ../source/key_projects.rst:661 -msgid "Pulp-python" -msgstr "Pulp-python" +"プロジェクトに合致する PyPI 分類子 のリスト。 `可能な分類子のリ" +"スト `_ を参照してください。" -#: ../source/key_projects.rst:663 +#: ../source/guides/writing-pyproject-toml.rst:393 msgid "" -"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +"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 "" -"`説明文書 `__ | :gh:`GitHub ` | `PyPI `__" +"あるプロジェクトが Python のどのバージョンをサポートしているのかを宣言するた" +"めに分類子 がよく使われますが、この情報は PyPI 上のプロジェクト" +"を検索し閲覧するためにのみ使われるのであって、プロジェクトをインストールする" +"ためには使われません。あるプロジェクトが Python のどのバージョンでならインス" +"トールされ得るのかを実際に制約するためには、 :ref:`requires-python` 引数を" +"使ってください。" -#: ../source/key_projects.rst:667 +#: ../source/guides/writing-pyproject-toml.rst:398 msgid "" -"Pulp-python is the Python :term:`package index ` plugin for " -"`Pulp `_. Pulp-python supports mirrors backed by " -"local or `AWS S3`_, package upload, and proxying to multiple package indexes." +"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 "" -"Pulp-python は、 `Pulp ` 向けの Python :term:`パッ" -"ケージインデックス ` プラグインです。 Pulp-python は、ローカル" -"か `AWS S3`_ にファイルを置くミラー機能や、複数のパッケージインデックスへのプ" -"ロクシ機能をサポートします。" +"パッケージが PyPI にアップロードされるのを防ぐには、 ``Private :: Do Not " +"Upload`` 分類子を使いましょう。``Private ::`` で始まる分類子を付けられたパッ" +"ケージを PyPI は常に拒否します。" -#: ../source/key_projects.rst:675 -msgid "PyPI Cloud" -msgstr "PyPI クラウド" +#: ../source/guides/writing-pyproject-toml.rst:404 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 +msgid "``urls``" +msgstr "``urls``" -#: ../source/key_projects.rst:677 +#: ../source/guides/writing-pyproject-toml.rst:406 msgid "" -"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." msgstr "" -"`説明文書 `__ | :gh:`GitHub ` | `PyPI `__" +"プロジェクトに関連のある URL のリストで、PyPI 上のプロジェクトページの左サイ" +"ドバーに表示されるもの。" -#: ../source/key_projects.rst:683 +#: ../source/guides/writing-pyproject-toml.rst:418 msgid "" -"PyPI Cloud is a :term:`package index ` server, backed by `AWS " -"S3`_ or another cloud storage service, or local files. PyPI Cloud supports " -"redirect/cached proxying for PyPI, as well as authentication and " -"authorisation." +"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 "" -"PyPI クラウドは、`AWS S3`_ や他のクラウドストレージサービス、あるいはローカル" -"のファイル群で裏打ちされた :term:`パッケージインデックス ` で" -"す。PyPI クラウドは、認証や認可と同様に PyPI に対するリダイレクト機能やプロク" -"シ機能をサポートします。" +"もしキーが空白文字を含んでいるなら、例えば ``Website = \"https://example." +"com\"`` ではなくて ``\"Official Website\" = \"https://example.com\"`` のよう" +"に引用符で囲む必要があります。" -#: ../source/key_projects.rst:691 -msgid "pypiprivate" -msgstr "pypiprivate" +#: ../source/guides/writing-pyproject-toml.rst:425 +msgid "Advanced plugins" +msgstr "先進的なプラグイン" -#: ../source/key_projects.rst:693 +#: ../source/guides/writing-pyproject-toml.rst:427 msgid "" -":gh:`GitHub ` | `PyPI `__" +"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 "" -":gh:`GitHub ` | `PyPI `__" +"パッケージの中にはプラグインを使って拡張できるものがあります。例としては、" +"Pytest_ や Pygments_ が挙げられます。そのようなプラグインを作成するためには、" +"以下のように ``[project.entry-points]`` のサブテーブルで宣言する必要がありま" +"す:" -#: ../source/key_projects.rst:696 -msgid "" -"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as a :" -"term:`package index `." +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -"pypiprivate は、 :term:`パッケージインデックス ` としてローカ" -"ルの (または `AWS S3`_ でホストされた) パッケージディレクトリを提供します。" +"詳しくは、 :ref:`プラグインガイド ` を見てください。" -#: ../source/key_projects.rst:702 -msgid "pypiserver" -msgstr "pypiserver" +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "A full example" +msgstr "完全な例" -#: ../source/key_projects.rst:704 +#: ../source/guides/writing-pyproject-toml.rst:503 msgid "" -"`GitHub `__ | `PyPI `__" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." msgstr "" -"`GitHub `__ | `PyPI `__" +"ここで ``requires-python = \"<=3.10\"`` のような上限を設定する前に、よくよく" +"考えてください。起きる可能性のある問題に関するいくらかの情報が `このブログ記" +"事 `_ にあります。" -#: ../source/key_projects.rst:707 +#: ../source/index.rst:-1 msgid "" -"pypiserver is a minimalist application that serves as a private Python :term:" -"`package index ` (from a local directory) within " -"organizations, implementing a simple API and browser interface. You can " -"upload private packages using standard upload tools, and users can download " -"and install them with :ref:`pip`, without publishing them publicly. " -"Organizations who use pypiserver usually download packages both from " -"pypiserver and from PyPI." +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." msgstr "" -"pypiserver は、単純な API とブラウザ向けのインタフェイスだけを実装した (ロー" -"カルディレクトリ上の) 組織内部向けプライベート Python :term:`パッケージイン" -"デックス ` として振る舞う「小さいことは良いことだ」主義者のア" -"プリケーションです。公衆向けに公開することなく標準のツールを使って外部非公開" -"のパッケージをアップロードすることもできますし、それを `pip` でダウンロード・" -"インストールすることもできます。 pypiserver を用いる組織では、通常は " -"pypiserver と PyPI の両方からパッケージをダウンロードします。" +"Python パッケージングユーザガイド (PyPUG) は、Python ソフトウェアのパッケージ" +"ングに関するチュートリアルやガイドを集めたものです。" -#: ../source/key_projects.rst:718 -msgid "PyScaffold" -msgstr "PyScaffold" +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "python ・ パッケージング・ガイド・チュートリアル" -#: ../source/key_projects.rst:720 +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "Pythonパッケージユーザーガイド（Python Packaging User Guide）" + +#: ../source/index.rst:25 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"Welcome to the *Python Packaging User Guide*, a collection of tutorials and " +"references to help you distribute and install Python packages with modern " +"tools." msgstr "" -"`説明文書 `__ | `GitHub `__ | `PyPI `__" +"*Python パッケージングユーザガイド* へようこそ、チュートリアルとリファレンス" +"であなたが近代的なツールを使ってパッケージを配布・インストールするのをお手伝" +"いします。" -#: ../source/key_projects.rst:724 +#: ../source/index.rst:29 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 " -"sane default configurations for established tools (such as :ref:" -"`setuptools`, pytest_ and Sphinx_) to provide a productive environment so " -"developers can start coding right away. PyScaffold can also be used with " -"existing projects to make packaging easier." +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" msgstr "" -"PyScaffold は、Python パッケージが PyPI で共有できて :ref:`pip` でインストー" -"ルできるように初期設定を行うプロジェクトジェネレータです。定評のあるツール (:" -"ref:`setuptools` や pytest_ や Sphinx_) 用に穏当なデフォルト設定を与えること" -"で、開発者がすぐにコードを書き始められるような生産的な環境を提供します。 " -"PyScaffold は、また、既存のプロジェクトにおいてもパッケージングをより簡単にす" -"るために使用することができます。" +"このガイドは、:doc:`Python パッケージングオーソリティ ` によって " +"`GitHub`_ 上で維持管理されています。:doc:`貢献とフィードバック ` " +"を大いに歓迎します。😊" -#: ../source/key_projects.rst:735 -msgid "pywharf" -msgstr "pywharf" +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "概要と流れ" -#: ../source/key_projects.rst:737 +#: ../source/index.rst:40 msgid "" -":gh:`GitHub ` | `PyPI `__" +"Building your understanding of Python packaging is a journey. Patience and " +"continuous improvement are key to success. The overview and flow sections " +"provide a starting point for understanding the Python packaging ecosystem." msgstr "" -":gh:`GitHub ` | `PyPI `__" +"Python のパッケージングに関する理解を醸成することは旅をするようなものです。忍" +"耐と継続的な改善が成功への鍵となります。概要と流れの章では、Python のパッケー" +"ジングのエコシステムを理解するための出発点を提供します。" -#: ../source/key_projects.rst:742 +#: ../source/index.rst:44 msgid "" -"pywharf is a :term:`package index ` server, serving files " -"locally or from `GitHub `_." +"The :doc:`overview` 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." msgstr "" -"pywharf は、ローカルから、もしくは `GitHub `_ からファイ" -"ルを提供する :term:`パッケージインデックス ` です。" - -#: ../source/key_projects.rst:748 -msgid "scikit-build" -msgstr "scikit-build" +":doc:`概要 ` では、 Python でのパッケージングとプロジェクトを準備し" +"て配布する時にどのように使うかを説明します。この節では、ツールの選定やユース" +"ケースに最適なプロセスについての理解を醸成します。パッケージングとは何か、そ" +"れが解決する問題、そして鍵となる考慮事項を含みます。" -#: ../source/key_projects.rst:750 +#: ../source/index.rst:51 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"To get an overview of the workflow used to publish your code, see :doc:" +"`packaging flow `." msgstr "" -"`説明文書 `__ | `GitHub " -"`__ | `PyPI `__" +"あなたのソースコードを公開するために用いられるワークフローの概要を得たけれ" +"ば、 :doc:`パッケージングフロー ` を見てください。" -#: ../source/key_projects.rst:754 +#: ../source/index.rst:57 msgid "" -"Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" -"Fortran/Cython extensions It 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)." -msgstr "" -"Scikit-build は、C/C++/Fortran/Cython で書かれた拡張をビルドする CPython のた" -"めの :ref:`setuptools` ラッパです。追加のコンパイラやビルドシステムやクロスコ" -"ンパイルに対するより良いサポートを提供するため、また、関連するビルドで要求さ" -"れるライブラリなど の位置を特定するために `cmake " -"`__ (PyPI にあります) を使用します。大きなプ" -"ロジェクトのビルドの速度を増したり並列化したりするために、ユーザは `ninja " -"`___ (これも PyPI にあります) をインストール" -"することができます。" - -#: ../source/key_projects.rst:765 -msgid "scikit-build-core" -msgstr "scikit-build-core" +"Tutorials walk through the steps needed to complete a project for the first " +"time. Tutorials aim to help you succeed and provide a starting point for " +"future exploration. The :doc:`tutorials/index` section includes:" +msgstr "" +"チュートリアルでは、初めてプロジェクトを完成させる際に必要な諸段階を一通り眺" +"めます。チュートリアルは、将来の探検のための出発点を提供することであなたの成" +"功を助けます。 :doc:`チュートリアル ` の節には次のものが含ま" +"れます:" -#: ../source/key_projects.rst:767 +#: ../source/index.rst:62 msgid "" -"`Docs `__ | `GitHub " -"`__ | `PyPI `__" +"A :doc:`tutorial on installing packages `" msgstr "" -"`説明文書 `__ | `GitHub " -"`__ | `PyPI `__" +":doc:`パッケージをインストールするためのチュートリアル `" -#: ../source/key_projects.rst:771 +#: ../source/index.rst:63 msgid "" -"Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " -"extensions. It enables users to write extensions with `cmake `__ (available on PyPI) to provide better support for " -"additional compilers, build systems, cross compilation, and locating " -"dependencies and their associated build requirements. CMake/Ninja are " -"automatically downloaded from PyPI if not available on the system." +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" msgstr "" -"Scikit-build-core は、CPython C/C++/Fortran/Cython による拡張モジュールのため" -"のビルドバックエンドです。追加のコンパイラやビルドシステムやクロスコンパイ" -"ル、また、依存関係とそれに付随するビルド時の要求事項を解決する点でより良いサ" -"ポートを提供するために、ユーザが `cmake `__ " -"(PyPI から利用可能) を使って拡張を書くことができるようにします。 CMake/Ninja " -"は、もしシステム上に利用可能なものがなければ、 PyPI から自動的にダウンロード" -"されます。" +"バージョンを管理しているプロジェクトでの :doc:`アプリケーションの依存関係を管" +"理するためのチュートリアル `" -#: ../source/key_projects.rst:781 -msgid "shiv" -msgstr "shiv" +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" +"あなたのプロジェクトの :doc:`パッケージングと配布のためのチュートリアル " +"`" -#: ../source/key_projects.rst:783 +#: ../source/index.rst:71 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"Guides provide steps to perform a specific task. Guides are more focused on " +"users who are already familiar with Python packaging and are looking for " +"specific information." msgstr "" -"`説明文書 `__ | `GitHub `__ | `PyPI `__" +"ガイド文書は、特定のタスクを実行するためのステップを提供します。ガイド文書" +"は、すでに Python のパッケージングに慣れていて、特定の情報を探しているような" +"ユーザに、より強く焦点を合わせています。" -#: ../source/key_projects.rst:787 +#: ../source/index.rst:75 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. " -"Its primary goal is making distributing Python applications and command line " -"tools fast & easy." +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." msgstr "" -"shiv は、 :pep:`441` に概要が示されている完全自己完結型 Python zipapp である" -"が必要な依存先をすべて内包したものをビルドするためのコマンドラインユーティリ" -"ティです。このツールの第一の目標は、Python アプリケーションとコマンドライン" -"ツールを素早く簡便に配布できるようにすることです。" +":doc:`ガイド ` 節では、パッケージインストール; パッケージの作成" +"と配布; その他の話題という３個の主要な分野について \"ハウツー \" とな" +"る指示を提供します。" -#: ../source/key_projects.rst:795 -msgid "simpleindex" -msgstr "simpleindex" +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "説明と議論" -#: ../source/key_projects.rst:797 +#: ../source/index.rst:82 msgid "" -":gh:`GitHub ` | `PyPI `__" +"The :doc:`discussions/index` section for in-depth explanations and " +"discussion about topics, such as:" msgstr "" -":gh:`GitHub ` | `PyPI `__" +"以下に述べるような話題に関する詳細に渡る説明と議論のための :doc:`議論 " +"` の節:" -#: ../source/key_projects.rst:800 -msgid "" -"simpleindex is a :term:`package index ` which routes URLs to " -"multiple package indexes (including PyPI), serves local (or cloud-hosted, " -"for example `AWS S3`_, with a custom plugin) directories of packages, and " -"supports custom plugins." +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" msgstr "" -"simple index は、 URL を (PyPI を含む) 複数のパッケージインデックスに振り分" -"け、ローカルの (または、カスタムプラグインを使って例えば `AWS S3`_ のようなク" -"ラウドにホストされた) パッケージディレクトリからファイルを提供し、カスタムプ" -"ラグインをサポートしている :term:`パッケージインデックス ` で" -"す。" +":doc:`議論/Pythonアプリの設置 `" -#: ../source/key_projects.rst:810 +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr ":doc:`議論/pip対easy-install `" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "参考文献" + +#: ../source/index.rst:91 msgid "" -":doc:`Docs ` | `GitHub `__ | " -"`Paper `__ | `Slides `__" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." msgstr "" -":doc:`説明文書 ` | `GitHub `__ " -"| `論文 `__ | `スライド `__" +"パッケージングに関する相互運用性の仕様については、 :doc:`仕様 " +"` を見てください。" -#: ../source/key_projects.rst:815 +#: ../source/index.rst:92 msgid "" -"A flexible package manager designed to support multiple versions, " -"configurations, platforms, and compilers. Spack is like Homebrew, but " -"packages are written in Python and parameterized to allow easy swapping of " -"compilers, library versions, build options, etc. Arbitrarily many versions " -"of packages can coexist on the same system. Spack was designed for rapidly " -"building high performance scientific applications on clusters and " -"supercomputers." +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." msgstr "" -"(spack は) 複数のバージョン・設定・プラットフォーム・コンパイラをサポートする" -"ように設計された自由度の高いパッケージマネージャです。 Spack は Homebrew に似" -"ていますが、Python で書かれていてコンパイラやライブラリのバージョン、ビルドオ" -"プションなどが簡単に入れ替えることができるようにパラメータ化されています。同" -"一のシステムの中に任意のバージョンのパッケージをいくつも同居させることができ" -"ます。 Spack は、元々はクラスタ構成のコンピュータ群やスーパーコンピュータの上" -"で科学分野の高パフォーマンスアプリケーションを素早くビルドするために設計され" -"ました。" +"Python パッケージングオーソリティのメンバーが維持管理している :doc:`他のプロ" +"ジェクト群 ` のリスト。" -#: ../source/key_projects.rst:823 -msgid "" -"Spack is not in PyPI (yet), but it requires no installation and can be used " -"immediately after cloning from GitHub." +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." msgstr "" -"Spack は (まだ) PyPI にありませんが、 GitHub からクローンした直後にインストー" -"ル作業なしで使用できます。" +"Python パッケージングで使われる用語の定義についての :doc:`語彙集 " +"` 。" -#: ../source/key_projects.rst:829 -msgid "zest.releaser" -msgstr "zest.releaser" +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "プロジェクト概要" -#: ../source/key_projects.rst:831 +#: ../source/key_projects.rst:8 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." msgstr "" -"`説明文書 `__ | `GitHub " -"`__ | `PyPI `__" +"Python の実装やパッケージングの領域で最も関連があるプロジェクト群へのまとめと" +"リンク。" -#: ../source/key_projects.rst:835 +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "PyPA プロジェクト群" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "bandersnatch" + +#: ../source/key_projects.rst:21 msgid "" -"``zest.releaser`` is a Python package release tool providing an abstraction " -"layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " -"automate incrementing package version numbers, updating changelogs, tagging " -"releases in source control, and uploading new packages to PyPI." +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" msgstr "" -"``zest.releaser`` は、 :ref:`twine` の上に抽象レイヤを提供する Python パッ" -"ケージのリリースツールです。 Python 開発者は ``zest.releaser`` を使ってパッ" -"ケージバージョンを増加させたり、変更履歴 (Changelog) を更新したり、ソースコー" -"ド管理の側でリリースタグを挿入したり、新しいパッケージを PyPI にアップロード" -"することを自動化することができます。" +"`説明文書 `__ | `課題リスト `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:842 -msgid "Standard Library Projects" -msgstr "標準ライブラリ内のプロジェクト群" +#: ../source/key_projects.rst:26 +msgid "" +"``bandersnatch`` is a PyPI mirroring client designed to efficiently create a " +"complete mirror of the contents of PyPI. Organizations thus save bandwidth " +"and latency on package downloads (especially in the context of automated " +"tests) and to prevent heavily loading PyPI's Content Delivery Network (CDN). " +"Files can be served from a local directory or `AWS S3`_." +msgstr "" +"``bandersnatch`` は、PyPI をミラーリングするクライアントで、PyPI のコンテンツ" +"の完全なコピーを効率よく作成するように設計されています。組織から見ると、これ" +"によってパッケージのダウンロードに必要な帯域幅とレイテンシーを (とりわけ自動" +"化されたテストの文脈で) 節約することができ、PyPI のコンテンツデリバリネット" +"ワーク (CDN) への負荷を軽減します。ローカルのディレクトリからでも `AWS S3`_ " +"からでもファイル群を提供するようにできます。" -#: ../source/key_projects.rst:847 -msgid "ensurepip" -msgstr "ensurepip" +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "ビルド" -#: ../source/key_projects.rst:849 +#: ../source/key_projects.rst:39 msgid "" -"`Docs `__ | `Issues " -"`__" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" msgstr "" -"`説明文書 `__ | `課題リス" -"ト `__" +":any:`文書 ` | `課題リスト `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:852 +#: ../source/key_projects.rst:44 msgid "" -"A package in the Python Standard Library that provides support for " -"bootstrapping :ref:`pip` into an existing Python installation or virtual " -"environment. In most cases, end users won't use this module, but rather it " -"will be used during the build of the Python distribution." +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." msgstr "" -"このパッケージはPython の標準ライブラリ内のパッケージで、既存のインストール済" -"み Python 環境や仮想環境に :ref:`pip` を組み込むためのサポートを提供します。" -"ほとんどの場合にはエンドユーザがこのモジュールを使うことはなく、どちらかと言" -"えば Python 配布物のビルドの際に使われるでしょう。" +"``build`` は :pep:`517` 互換の Python パッケージビルダです。Python API と同様" +"に、パッケージをビルドする CLI を提供します。" -#: ../source/key_projects.rst:860 -msgid "http.server" -msgstr "http.server" +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" -#: ../source/key_projects.rst:862 +#: ../source/key_projects.rst:53 msgid "" -":doc:`Docs ` | :gh:`Issues `" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" msgstr "" -":doc:`説明文書 ` | :gh:`課題リスト `" +"`説明文書 `__ | `課題リスト `__ | `GitHub `__ | `PyPI `__ | `議論 " +"`__ | `Discord " +"#cibuildwheel `__" -#: ../source/key_projects.rst:865 +#: ../source/key_projects.rst:60 msgid "" -"A package and command-line interface which can host a directory as a " -"website, for example as a :term:`package index ` (see :ref:" -"`Hosting your Own Simple Repository`)." +"``cibuildwheel`` is a Python package that builds :term:`wheels ` for " +"all common platforms and Python versions on most CI systems. Also see :ref:" +"`multibuild`." msgstr "" -"ウェブサイトとして、つまり例えば :term:`パッケージインデックス ` として、ディレクトリを扱うことができるパッケージとコマンドラインイン" -"タフェース (:ref:`自分用のシンプルなリポジトリをホストする ` を参照してください) 。" +"``cibuildwheel`` は、プラットフォーム・ Python バージョン・ CIシステムのよく" +"ある組み合わせの全部について :term:`wheels ` をビルドする Python パッ" +"ケージです。" -#: ../source/key_projects.rst:872 -msgid "venv" -msgstr "venv" +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "distlib" -#: ../source/key_projects.rst:874 +#: ../source/key_projects.rst:68 msgid "" -"`Docs `__ | `Issues `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" msgstr "" -"`説明文書 `__ | `課題リスト " -"`__" +":doc:`文書 ` | `課題リスト `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:877 +#: ../source/key_projects.rst:73 msgid "" -"A package in the Python Standard Library (starting with Python 3.3) for " -"creating :term:`Virtual Environments `. For more " -"information, see the section on :ref:`Creating and using Virtual " -"Environments`." +"``distlib`` is a library which implements low-level functions that relate to " +"packaging and distribution of Python software. ``distlib`` implements " +"several relevant PEPs (Python Enhancement Proposal standards) and is useful " +"for developers of third-party packaging tools to make and upload binary and " +"source :term:`distributions `, achieve " +"interoperability, resolve dependencies, manage package resources, and do " +"other similar functions." msgstr "" -"(Python 3.3 から始まる) Python の標準ライブラリに存在する :term:`仮想環境 " -"` を生成するためのパッケージ。更なる情報については :ref:" -"`仮想環境を作って使う ` を見てくださ" -"い。" - -#: ../source/news.rst:2 -msgid "News" -msgstr "ニュース" +"``distlib`` は、 Python ソフトウェアのパッケージングや配布に関係する低レベル" +"の機能を実装しているライブラリです。 ``distlib`` はいくつかの関連する PEP " +"(Python Enhancement Proposal standards) を実装していて、サードパーティのパッ" +"ケージングツールの開発者にとってバイナリやソースコードの :term:`配布物 " +"` を作成・アップロードしたり、相互運用性を確保したり、" +"依存関係を解決したり、パッケージリソースを管理したり、その他の類似の機能を実" +"行したりするのに便利です。" -#: ../source/news.rst:4 +#: ../source/key_projects.rst:82 msgid "" -"This document is not currently updated. Previously, the document highlighted " -"changes in Python packaging." +"Unlike the stricter :ref:`packaging` project (below), which specifically " +"implements modern Python packaging interoperability standards, ``distlib`` " +"also attempts to provide reasonable fallback behaviours when asked to handle " +"legacy packages and metadata that predate the modern interoperability " +"standards and fall into the subset of packages that are incompatible with " +"those standards." msgstr "" -"この文書は現在では更新されていません。以前は、Python パッケージングでの変更点" -"をハイライトしていました。" +"近代的な Python パッケージングにおける相互運用性標準に特に気を配って実装され" +"た、より厳格な :ref:`packaging` プロジェクト (後述) とは異なり、 ``distlib`` " +"は近代的な相互運用性標準ができる前の昔ながらのパッケージやメタデータで今と" +"なってはその標準に外れたことになっているものを扱うように言われた時には合理的" +"なフォールバック動作も提供しようとしています。" -#: ../source/news.rst:9 -msgid "September 2019" -msgstr "2019年9月" +#: ../source/key_projects.rst:93 +msgid "distutils" +msgstr "distutils" -#: ../source/news.rst:10 -msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +#: ../source/key_projects.rst:95 +msgid "" +"The original Python packaging system, added to the standard library in " +"Python 2.0 and removed in 3.12." msgstr "" -"GitHub Actions を経由して配布物を公開するためのガイドを追加。 (:pr:`647`)" - -#: ../source/news.rst:13 -msgid "August 2019" -msgstr "2019年8月" +"Python の元々のパッケージングシステムで、Python 2.0 の時点で標準ライブラリに" +"追加され 3.12 で削除されました。" -#: ../source/news.rst:14 -msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +#: ../source/key_projects.rst:98 +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` has been 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." msgstr "" -"pipx をインストールする際に :file:`python3 -m` を使うように更新。 (:pr:`631`)" - -#: ../source/news.rst:17 -msgid "July 2019" -msgstr "2019年7月" - -#: ../source/news.rst:18 -msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" -msgstr "すべての PEP 番号を :pep: 役割の形にした。 (:pr:`629`)" +"パッケージングシステムを維持管理する際の難題には機能向上が言語ラインタイムの" +"更新と密接に結びついていることが挙げられますが、そのせいで :ref:`distutils` " +"を直接に使用することは強い非推奨事項にずっとなり続けてきており、代わりに :" +"ref:`Setuptools` を使うことが望ましいとされています。 :ref:`Setuptools` " +"は、 :ref:`distutils` そのものが提供していない機能 (例えば依存関係の宣言やエ" +"ントリポイントの宣言) を提供できるだけでなく、守備一貫したビルド用のインタ" +"フェイスやサポートするすべてのバージョンの Python のすべてについて設定できる" +"機能を提供しています。" -#: ../source/news.rst:19 -msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +#: ../source/key_projects.rst:107 +msgid "" +"Consequently, :ref:`distutils` was deprecated in Python 3.10 by :pep:`632` " +"and has been :doc:`removed ` from the standard library " +"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 "" -"Sphinx のバージョンを上げ、papa.io の intersphinx を削除した。 (:pr:`625`)" +"従って、 :ref:`distutils` は :pep:`632` によって Python 3.10 で非推奨にな" +"り、 Python 3.12 で標準ライブラリから :doc:`削除 ` され" +"ました。Setuptools にはスタンドアローンの distutils が同梱されていて、< 3.12 " +"の Python 上であっても setuptools をインポートするか pip を使うと注入されま" +"す。" -#: ../source/news.rst:20 -msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" -msgstr ":file:`find_namespace_packages` に言及した。 (:pr:`622`)" +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "flit" -#: ../source/news.rst:21 -msgid "Updated directory layout examples for consistency. (:pr:`611`)" -msgstr "一貫性確保のためにディレクトリ配置の例を更新した。 (:pr:`611`)" +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `課題リスト `__ | `PyPI `__" -#: ../source/news.rst:22 -msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" -msgstr "Bandersnatch の GitHub へのリンクを更新した。 (:pr:`623`)" +#: ../source/key_projects.rst:122 +msgid "" +"Flit provides a simple way to create and upload pure Python packages and " +"modules to PyPI. It focuses on `making the easy things easy `_ for packaging. Flit can generate a configuration file to " +"quickly set up a simple project, build source distributions and wheels, and " +"upload them to PyPI." +msgstr "" +"Flit は、純 Python のパッケージやモジュールを作成して PyPI へアップロードする" +"簡単な手段を提供します。パッケージングに関して `簡単なことを簡単に実現する " +"`_ ことに注力しています。これを使えば単純なプロジェクトや" +"ソースコード配布物とwheelsについて素早くセットアップするための設定ファイルを" +"生成し、PyPI にアップロードすることができます。" -#: ../source/news.rst:25 -msgid "June 2019" -msgstr "2019年6月" +#: ../source/key_projects.rst:127 +msgid "" +"Flit uses ``pyproject.toml`` to configure a project. Flit does not rely on " +"tools such as :ref:`setuptools` to build distributions, or :ref:`twine` to " +"upload them to PyPI. Flit requires Python 3, but you can use it to " +"distribute modules for Python 2, so long as they can be imported on Python 3." +msgstr "" +"Flit は、 ``pyproject.toml`` を使ってプロジェクトの設定を行います。Flit は、" +"配布物をビルドする :ref:`setuptools` やそれを PyPI へアップロードする :ref:" +"`twine` のようなツールには依存していません。 Flit は Python 3 を要求します" +"が、Python 3 上にインポートできるものであれば Python 2 向けのモジュールでも配" +"布することが可能です。" -#: ../source/news.rst:26 -msgid "Fixed some typos. (:pr:`620`)" -msgstr "いくつかの誤記を訂正した。 (:pr:`620`)" +#: ../source/key_projects.rst:132 +msgid "" +"The flit package is lifted by `Matthias Bussonnier `__ since October 2023 on the `tidelift platform `__, and funds sent to the PSF and earmarked for " +"PyPA usage." +msgstr "" +"flit パッケージは、2023年10月以来、 `tidelift platform `__ でリフト (訳註、維持管理に対して対価を払う" +"の意か) され、また、PSF に送られたファンドで PyPA 向けに使うように指定された" +"資金を使って、 `Matthias Bussonnier `__ によって" +"維持管理されています。" -#: ../source/news.rst:29 -msgid "May 2019" -msgstr "2019年5月" +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "hatch" -#: ../source/news.rst:30 -msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -":file:`python_requires` の使い方をパッケージングチュートリアルに追記した。 (:" -"pr:`613`)" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:31 -msgid "Added a MANIFEST.in guide page. (:pr:`609`)" -msgstr "MANIFEST.in について説明するページを追加した。 (:pr:`609`)" +#: ../source/key_projects.rst:148 +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 :term:`build backend ` Hatchling " +"to configure, version, specify dependencies for, and publish packages to " +"PyPI. Its plugin system allows for easily extending functionality." +msgstr "" +"Hatch は、 Python での開発者向けに依存関係の管理や環境の分離を便利に行うため" +"の統合されたコマンドラインツールです。 Python パッケージ開発者は Hatch とそ" +"の :term:`ビルドバックエンド ` である Hatchling を使って、パッ" +"ケージの設定を実施し、バージョン管理を行い、依存関係を指定し、そして PyPI で" +"公開することができます。プラグインシステムがあるので、容易に機能を拡張するこ" +"とができます。" -#: ../source/news.rst:34 -msgid "April 2019" -msgstr "2019年4月" +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "packaging ライブラリ" -#: ../source/news.rst:35 +#: ../source/key_projects.rst:159 msgid "" -"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" msgstr "" -":file:`shiv` への言及を嗅ぎとなるプロジェクト群の節に追加した。 (:pr:`608`)" - -#: ../source/news.rst:36 -msgid "Reduced emphasis on virtualenv. (:pr:`606`)" -msgstr "virtualenv に関する強調を減少させた。 (:pr:`606`)" +":doc:`説明文書 ` | `課題リスト `__ | `GitHub `__ | " +"`PyPI `__" -#: ../source/news.rst:39 -msgid "March 2019" -msgstr "2019年3月" +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" +"(packaging ライブラリには) :ref:`pip` や :ref:`setuptools` で使われる Python " +"パッケージングのための中核的なユーティリティ (としての core utilities があり" +"ます)。" -#: ../source/news.rst:40 -msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +#: ../source/key_projects.rst:166 +msgid "" +"The core utilities in the packaging library handle version handling, " +"specifiers, markers, requirements, tags, and similar attributes and tasks " +"for Python packages. Most Python users rely on this library without needing " +"to explicitly call it; developers of the other Python packaging, " +"distribution, and installation tools listed here often use its functionality " +"to parse, discover, and otherwise handle dependency attributes." msgstr "" -"「パッケージのバージョンを１箇所で管理する」の項を Python 3 側に移した。 (:" -"pr:`605`)" +"packaging ライブラリの core utilities は、バージョンの取り扱い、識別子、マー" +"カ、依存先パッケージ、タグ、その他これに類似した属性やタスクを取り扱います。 " +"Python ユーザのほとんどは、明示的に呼び出す必要に迫られることはなくともこのラ" +"イブラリに依存しています; ここにリストされているような Python のパッケージン" +"グや配布やインストールを扱う他のパッケージを開発する者は、パースしたり検出し" +"たりそうでなければ依存関係の属性を取り扱うようなこのライブラリの機能をしばし" +"ば利用しています。" -#: ../source/news.rst:41 -msgid "Covered RTD details for contributing. (:pr:`600`)" -msgstr "RTD の詳細について貢献方法のところでカバーした。 (:pr:`600`)" +#: ../source/key_projects.rst:174 +msgid "" +"This project specifically focuses on implementing the modern Python " +"packaging interoperability standards defined at :ref:`packaging-" +"specifications`, and will report errors for sufficiently old legacy packages " +"that are incompatible with those standards. In contrast, the :ref:`distlib` " +"project is a more permissive library that attempts to provide a plausible " +"reading of ambiguous metadata in cases where :ref:`packaging` will instead " +"report on error." +msgstr "" +"このプロジェクトは、 :ref:`パッケージング仕様 `__ | `Issues `__ | `GitHub `__ | `PyPI `__" msgstr "" -"チュートリアルの内容と実際のパッケージングプロセスの間の差異について詳しく述" -"べた。 (:pr:`602`)" +"`説明文書 `__ | `課題リスト `__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:46 -msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." msgstr "" -"Python の CLI アプリケーションをインストールするための指示書きを追加した。 (:" -"pr:`594`)" - -#: ../source/news.rst:49 -msgid "January 2019" -msgstr "2019年1月" +"Python パッケージをインストールするに当たっての最もよく知られたツールで、" +"Python の新しめのバージョンには同梱されているもの。" -#: ../source/news.rst:50 -msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +#: ../source/key_projects.rst:196 +msgid "" +"It provides the essential core features for finding, downloading, and " +"installing packages from PyPI and other Python package indexes, and can be " +"incorporated into a wide range of development workflows via its command-line " +"interface (CLI)." msgstr "" -"パッケージングチュートリアルに :file:`--no-deps` を追加した。 (:pr:`593`)" - -#: ../source/news.rst:51 -msgid "Updated Sphinx and Nox. (:pr:`591`)" -msgstr "Sphinx と Nox について更新した。 (:pr:`591`)" +"PyPI やその他の Python パッケージインデックスのパッケージを探索・ダウンロー" +"ド・インストールするための基本的な機能を提供するとともに、コマンドラインイン" +"タフェイス (CLI) を通じて広範囲の開発ワークフローに組み込むことができます。" -#: ../source/news.rst:52 -msgid "Referenced Twine from Python3. (:pr:`581`)" -msgstr "Python 3 の項に Twine への言及を追加した。 (:pr:`581`)" +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "Pipenv" -#: ../source/news.rst:55 -msgid "December 2018" -msgstr "2018年12月" +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +msgstr "" +":doc:`説明文書 ` | `ソースコード `__ | `課題リスト `__ | `PyPI " +"`__" -#: ../source/news.rst:56 -msgid "No programmers in the office!" -msgstr "事務所にプログラマが居ません！" +#: ../source/key_projects.rst:211 +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 `_." +msgstr "" +"Pipenv は、全てのパッケージング世界の最良のものを Python 世界に持ち込むことを" +"目的とするプロジェクトです。 :ref:`Pipfile` ・ :ref:`pip` ・ :ref:" +"`virtualenv` を単一のツールチェーンにまとめ上げるものです。 ``requirements." +"txt`` を自動的にインポートすることができ、また、 `safety `_ を使って `Pipfile`_ 中の CVE を確認することができます。" -#: ../source/news.rst:59 -msgid "November 2018" -msgstr "2018年11月" +#: ../source/key_projects.rst:216 +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 checks file hashes, to ensure compliance " +"with hash-locked dependency specifiers, and eases uninstallation of packages " +"and dependencies." +msgstr "" +"Pipenv は、ユーザがコマンドラインで環境・依存関係・インポートされたパッケージ" +"を管理することを補助することを目的としています。 (他のツールが往々にしてうま" +"く動かない) Windows 上でもきちんと動作し、ファイルのハッシュ値を計算し確認す" +"ることでハッシュ値による依存関係識別子との互換性を確保し、パッケージの依存関" +"係先のアンインストールを容易にします。" -#: ../source/news.rst:60 -msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" -msgstr "PyPI 移行ガイドへのランディングページリンクを削除した。 (:pr:`575`)" +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "Pipfile" -#: ../source/news.rst:61 -msgid "Changed bumpversion to bump2version. (:pr:`572`)" -msgstr "bumpversion を bump2version に変更した。 (:pr:`572`)" +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "`ソースコード `__" -#: ../source/news.rst:62 -msgid "Added single-sourcing package version example. (:pr:`573`)" -msgstr "パッケージバージョンの一元管理の例を追加した。 (:pr:`573`)" +#: ../source/key_projects.rst:229 +msgid "" +":file:`Pipfile` and its sister :file:`Pipfile.lock` are a higher-level " +"application-centric alternative to :ref:`pip`'s lower-level :file:" +"`requirements.txt` file." +msgstr "" +":file:`Pipfile` とその姉妹 :file:`Pipfile.lock` は、 :ref:`pip` における低レ" +"ベルの :file:`requirements.txt` ファイルに代わる高レベルのアプリケーション中" +"心のファイルです。" -#: ../source/news.rst:63 -msgid "Added a guide for creating documentation. (:pr:`568`)" -msgstr "ドキュメント作成のためのガイドを追加した。 (:pr:`568`)" +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "pipx" -#: ../source/news.rst:66 -msgid "October 2018" -msgstr "2018年10月" +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:67 -msgid "Updated Nox package name. (:pr:`566`)" -msgstr "Nox パッケージの名称を更新した。 (:pr:`566`)" +#: ../source/key_projects.rst:242 +msgid "" +"pipx is a tool to install and run Python command-line applications without " +"causing dependency conflicts with other packages installed on the system." +msgstr "" +"pipx は、システムにインストール済みの他のパッケージとの間に依存関係の衝突を起" +"こすことなく Python のコマンドラインアプリケーションをインストールし動作させ" +"るためのツールです。" -#: ../source/news.rst:68 -msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" -msgstr "ガイドの中で Sphinx 拡張について言及した。 (:pr:`562`)" +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" +":doc:`説明文書 ` | `課題リスト `__ | `GitHub `__" -#: ../source/news.rst:71 -msgid "September 2018" -msgstr "2018年9月" +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "このガイド!" -#: ../source/news.rst:72 -msgid "Added a section on checking RST markup. (:pr:`554`)" -msgstr "RST マークアップの検査に関する節を追加した。 (:pr:`554`)" +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "readme_renderer" -#: ../source/news.rst:73 -msgid "Updated user installs page. (:pr:`558`)" -msgstr "ユーザによるインストールのページを更新した。 (:pr:`558`)" +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" +"`GitHub および説明文書 `__ | `PyPI " +"`__" -#: ../source/news.rst:74 -msgid "Updated Google BigQuery urls. (:pr:`556`)" -msgstr "Google BigQuery の url を更新した。 (:pr:`556`)" +#: ../source/key_projects.rst:263 +msgid "" +"``readme_renderer`` is a library that package developers use to render their " +"user documentation (README) files into HTML from markup languages such as " +"Markdown or reStructuredText. Developers call it on its own or via :ref:" +"`twine`, as part of their release management process, to check that their " +"package descriptions will properly display on PyPI." +msgstr "" +"``readme_renderer`` は、Markdown や reStructuredText のようなマークアップ言語" +"で書かれたユーザ向け説明ファイル (README) を HTML に展開するためにパッケージ" +"開発者が用いるライブラリです。開発者は、リリース管理プロセスの一環として直接" +"または :ref:`twine` 経由でこれを呼び出し、そのパッケージに関する説明がきちん" +"と PyPI に表示されることを確認します。" -#: ../source/news.rst:75 -msgid "Replaced tar command with working command. (:pr:`552`)" -msgstr "tar コマンドについて動作するコマンドに置換した。 (:pr:`552`)" +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "Setuptools" -#: ../source/news.rst:76 +#: ../source/key_projects.rst:276 msgid "" -"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" msgstr "" -"pip インストールで SomeProject==1.4 と書くところをダブルクォーテーションマー" -"クに変更した。 (:pr:`550`)" - -#: ../source/news.rst:79 -msgid "August 2018" -msgstr "2018年8月" - -#: ../source/news.rst:80 -msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" -msgstr "パスワードを平文で保存することを推奨していたのを削除した。 (:pr:`546`)" +"`説明文書 `__ | `課題リスト " +"`__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:81 +#: ../source/key_projects.rst:281 msgid "" -"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" -msgstr "他のものに加えて、概要をタスク別の見出しに移した。 (:pr:`540`)" - -#: ../source/news.rst:82 -msgid "Updated Python version supported by virtualenv. (:pr:`538`)" -msgstr "virtualenv がサポートする Python のバージョンを更新した。 (:pr:`538`)" - -#: ../source/news.rst:83 -msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" -msgstr "新しい概要のページのあらまし/ラフな下書きを追加した。 (:pr:`519`)" +"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 "" +"(``easy_install`` を含む) Setuptools は Python の distutils への拡張を集めた" +"もので、特に他のパッケージに依存関係がある場合に、より簡単に Python の :term:" +"`配布物 ` をビルドし配布することが可能となります。" -#: ../source/news.rst:86 -msgid "July 2018" -msgstr "2018年7月" +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "trove-classifiers" -#: ../source/news.rst:88 -msgid "Improved binary extension docs. (:pr:`531`)" -msgstr "バイナリ拡張に関する説明文書を改善した。 (:pr:`531`)" +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`課題リスト `__ | `GitHub " +"`__ | `PyPI `__" -#: ../source/news.rst:89 -msgid "Added scikit-build to key projects. (:pr:`530`)" -msgstr "scikit-build を主要プロジェクトに追加した。 (:pr:`530`)" +#: ../source/key_projects.rst:295 +msgid "" +"trove-classifiers is the canonical source for `classifiers on PyPI `_, 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 でよりうまく探" +"し出せるように、プロジェクトの保守者が `プロジェクトを体系的に表現する `_ のに使います。" -#: ../source/news.rst:92 -msgid "June 2018" -msgstr "2018年6月" +#: ../source/key_projects.rst:300 +msgid "" +"The trove-classifiers package contains a list of valid classifiers and " +"deprecated classifiers (which are paired with the classifiers that replace " +"them). Use this package to validate classifiers used in packages intended " +"for uploading to PyPI. As this list of classifiers is published as code, you " +"can install and import it, giving you a more convenient workflow compared to " +"referring to the `list published on PyPI `_. " +"The `issue tracker `_ for " +"the project hosts discussions on proposed classifiers and requests for new " +"classifiers." +msgstr "" +"trove-classifiers パッケージには、正当な分類子および (それを置き換えた分類子" +"と一組で) 非推奨になった分類子のリストが含まれています。 PyPI にアップロード" +"しようとしているパッケージで使われている分類子の正当性を確認するために、この" +"パッケージを使いましょう。この分類子リストがソースコードの形で公開されている" +"ので、それをインストールしてインポートすれば、 `PyPI で公開されているリスト " +"`_ を参照するよりももっと便利なワークフローを" +"構築することができます。本プロジェクトの `課題リスト `_ に、提案された分類子に関する議論や新しい分類" +"子が欲しいという要求に関する議論が公開されています。" -#: ../source/news.rst:94 -msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" -msgstr "pypa.io に関する相互運用性 PEP のカテゴリ分けを修正した。 (:pr:`527`)" +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "twine" -#: ../source/news.rst:95 -msgid "Updated Markdown descriptions explanation. (:pr:`522`)" -msgstr "descriptions をマークダウンで書く場合の説明を更新した。 (:pr:`522`)" +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | " +"`PyPI `__" +msgstr "" +"`説明文書 `__ | `課題リスト " +"`__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:98 -msgid "May 2018" -msgstr "2018年5月" +#: ../source/key_projects.rst:321 +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 " +"that passes program files and metadata to a web API. Developers use it " +"because it's the official PyPI upload tool, it's fast and secure, it's " +"maintained, and it reliably works." +msgstr "" +"Twine は、開発者がパッケージをPython パッケージインデックス (PyPI) や他の " +"Python 用パッケージインデックスへアップロードするのに使う最初の選択肢です。こ" +"れはコマンドラインプログラムで、プログラムのファイルやメタデータを web API へ" +"渡します。開発者がこれを使うのは、公式の PyPI へのアップロードツールであるか" +"らであり、動作が速く安全であるからであり、保守されているからであり、動作が信" +"頼できるからです。" -#: ../source/news.rst:100 -msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" -msgstr "Provides-Diet と Obsolete-Diet の課題を注記した。 (:pr:`513`)" +#: ../source/key_projects.rst:331 ../source/overview.rst:401 +msgid "virtualenv" +msgstr "virtualenv" -#: ../source/news.rst:101 +#: ../source/key_projects.rst:333 msgid "" -"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" msgstr "" -"Pipenv で異なるバージョンの Python を使う場合の警告が古くなっていたので削除し" -"た。 (:pr:`501`)" - -#: ../source/news.rst:102 -msgid "Simplified packaging tutorial. (:pr:`498`)" -msgstr "パッケージングのチュートリアルを簡素にした。 (:pr:`498`)" +"`説明文書 `__ | `課題リスト " +"`__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:103 -msgid "Updated Windows users instructions for clarity. (:pr:`493`)" -msgstr "明確性のため、 Windows ユーザ向けの指示を更新した。 (:pr:`493`)" +#: ../source/key_projects.rst:338 +msgid "" +"virtualenv is a tool for creating isolated Python :term:`Virtual " +"Environments `, like :ref:`venv`. Unlike :ref:`venv`, " +"virtualenv can create virtual environments for other versions of Python, " +"which it locates using the PATH environment variable. It also provides " +"convenient features for configuring, maintaining, duplicating, and " +"troubleshooting virtual environments. For more information, see the section " +"on :ref:`Creating and using Virtual Environments`." +msgstr "" +"virtualenv は、 :ref:`venv` と同様に独立した Python :term:`仮想環境 ` を生成するツールです。 :ref:`venv` とは異なり、virtualenv は " +"PATH 環境変数を使って特定することで他のバージョンの Python 用の仮想環境を作成" +"することができます。他にも、仮想環境の設定・保守・複製・問題解決のための便利" +"な機能を提供しています。より詳しくは、 :ref:`仮想環境を作って使う ` の節を見てください。" -#: ../source/news.rst:104 -msgid "Updated the license section description for completeness. (:pr:`492`)" -msgstr "完全性のためにライセンスの節の記述を更新した。 (:pr:`492`)" +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "Warehouse" -#: ../source/news.rst:105 -msgid "Added specification-style document to contributing section. (:pr:`489`)" -msgstr "「貢献するには」の節に仕様のスタイルの記述を追加した。 (:pr:`489`)" +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" +"`説明文書 `__ | `課題リスト `__ | `GitHub `__" -#: ../source/news.rst:106 -msgid "Added documentation types to contributing guide. (:pr:`485`)" -msgstr "「貢献するには」ガイドにドキュメントのタイプを追記した。 (:pr:`485`)" +#: ../source/key_projects.rst:356 +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 "" +"現在の :term:`Python パッケージインデックス ` を" +"構成しているコードベース。 `pypi.org `_ にホストされていま" +"す。 :ref:`pip` がダウンロードする際のデフォルトのソースです。" -#: ../source/news.rst:109 -msgid "April 2018" -msgstr "2018年4月" +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "wheel" -#: ../source/news.rst:111 -msgid "Added README guide. (:pr:`461`)" -msgstr "README ガイドを追加した。 (:pr:`461`)" +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | " +"`PyPI `__" +msgstr "" +"`説明文書 `__ | `課題リスト " +"`__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:112 -msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" -msgstr "PyPI の供用開始についてやり方と状態を更新した。 (:pr:`475`)" +#: ../source/key_projects.rst:371 +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 "" +"wheel は、主として :term:`wheel 配布物 ` を作成するための :ref:" +"`setuptools` の拡張である ``bidet_wheel`` を提供するプロジェクトです。この他" +"にも、wheel ファイルを作成しインストールするためのコマンドラインユーティリ" +"ティを提供します。" -#: ../source/news.rst:113 -msgid "Added instructions for Warehouse. (:pr:`471`)" -msgstr "Warehouse についての指示を追加した。 (:pr:`471`)" +#: ../source/key_projects.rst:375 +msgid "" +"See also `auditwheel `__, a tool that " +"package developers use to check and fix Python packages they are making in " +"the binary wheel format. It provides functionality to discover dependencies, " +"check metadata for compliance, and repair the wheel and metadata to properly " +"link and include external shared libraries in a package." +msgstr "" +"パッケージ開発者がバイナリの wheel フォーマットで開発中の Python パッケージを" +"チェックし問題を解決するためのツールである `auditwheel `__ も見てください。このツールは、依存関係を検出し、法令遵守" +"のためのメタデータを確認し、 wheel とメタデータがパッケージないの外部共有ライ" +"ブラリに正しくリンクしインクルードするように修正する機能を提供します。" -#: ../source/news.rst:114 -msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" -msgstr "" -"(パッケージを?) 公開するチュートリアルから GPG の参照情報を削除した。 (:pr:" -"`466`)" +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "非 PyPA プロジェクト" -#: ../source/news.rst:115 -msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" -msgstr "「Python 3.4-3.6 では何がどれに入ってる？」を追加した。 (:pr:`468`)" +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "buildout" -#: ../source/news.rst:116 -msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -"あるバージョンの Python を徐々に使わなくするガイドを追加した。 (:pr:`459`)" +"`説明文書 `__ | `課題リスト `__ | `PyPI `__ | `GitHub `__" -#: ../source/news.rst:117 -msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +#: ../source/key_projects.rst:396 +msgid "" +"Buildout is a Python-based build system for creating, assembling and " +"deploying applications from multiple parts, some of which may be non-Python-" +"based. It lets you create a buildout configuration and reproduce the same " +"software later." msgstr "" -"変種の GFM をデフォルトの Description-Content-Type とした。 (:pr:`462`)" +"Buildout は Python ベースのビルドシステムで、非 Python ベースのものを含む複数" +"の部品から構成されるアプリケーションの生成・組み立て・配置ができます。" +"buildout の設定を作っておけば、後で同じソフトウェアを再生成することができま" +"す。" -#: ../source/news.rst:120 -msgid "March 2018" -msgstr "2018年3月" +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "conda" -#: ../source/news.rst:122 -msgid "Updated \"installing scientific packages\". (:pr:`455`)" -msgstr "「科学計算分野のパッケージ群」を更新した。 (:pr:`455`)" +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr ":doc:`説明文書 `" -#: ../source/news.rst:123 +#: ../source/key_projects.rst:407 msgid "" -"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +"conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " +"from `Anaconda, Inc `__ " +"specifically aimed at the scientific community, and in particular on Windows " +"where the installation of binary extensions is often difficult." msgstr "" -"PEP 556 に従う :file:`long_description_content_type` を追加した。 (:pr:`457`)" +"conda は、 Python 実装である `Anaconda `__ のためのパッケージ管理ツールです。Anaconda Python は、 `Anaconda, Inc " +"`__ が特に科学計算の分野に向け" +"て配布している配布物で、とりわけ通常ならバイナリ拡張のインストールが難しいと" +"される Windows 用に配布しています。" -#: ../source/news.rst:124 -msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +#: ../source/key_projects.rst:414 +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 "" -"pypi.org における long description 分類子について明確化した。 (:pr:`456`)" +"Conda は、 :ref:`pip` や virtualenv や wheel とは全く別のツールですが、パッ" +"ケージ管理・仮想環境管理・バイナリ拡張のデプロイメントの観点ではこれらのツー" +"ルを合わせたような機能を提供します。" -#: ../source/news.rst:125 -msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" -msgstr "コアとなるメタデータ仕様が PEP 556 に従うように更新した。 (:pr:`412`)" +#: ../source/key_projects.rst:418 +msgid "" +"Conda does not install packages from PyPI and can install only from the " +"official Anaconda repositories, or anaconda.org (a place for user-" +"contributed *conda* packages), or a local (e.g. intranet) package server. " +"However, note that :ref:`pip` can be installed into, and work side-by-side " +"with conda for managing :term:`distributions ` from " +"PyPI. Also, `conda skeleton `__ is a tool to make " +"Python packages installable by conda by first fetching them from PyPI and " +"modifying their metadata." +msgstr "" +"Conda は PyPI からパッケージをインストールすることはなく、公式の Anaconda リ" +"ポジトリか、anaconda.org (ユーザが貢献した *conda* パッケージの置き場所) か、" +"または、ローカル (例えばイントラネット) にあるパッケージサーバからのみインス" +"トールすることができます。しかしながら、:ref:`pip` をインストールすることは可" +"能で、PyPI からの :term:`配布物 ` の管理という点では " +"conda と平行して動作することができます。また、 `conda skeleton `__ は、 PyPI から持ってきた Python パッケージのメタデータを修" +"正することで conda がインストールできるものにするためのツールです。" -#: ../source/news.rst:128 -msgid "February 2018" -msgstr "2018年2月" +#: ../source/key_projects.rst:431 +msgid "devpi" +msgstr "devpi" -#: ../source/news.rst:130 +#: ../source/key_projects.rst:433 msgid "" -"Added python3-venv and python3-pip to Debian installation instructions. (:pr:" -"`445`)" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" msgstr "" -"Debian でのインストール指示に python3-venv と python3-pip を追記した。 (:pr:" -"`445`)" - -#: ../source/news.rst:131 -msgid "Updated PyPI migration info. (:pr:`439`)" -msgstr "PyPI 移行情報を更新した。 (:pr:`439`)" +"`説明文書 `__ | :gh:`課題リスト ` | `PyPI `__" -#: ../source/news.rst:132 +#: ../source/key_projects.rst:437 msgid "" -"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +"devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " +"complementary command line tool to drive packaging, testing and release " +"activities with Python. devpi also provides a browsable and searchable web " +"interface. devpi supports mirroring PyPI, multiple :term:`package indexes " +"` with inheritance, syncing between these indexes, index " +"replication and fail-over, and package upload." msgstr "" -"複数のバージョンの pipenv を取り扱う際の注意事項を追記した。 (:pr:`430`)" +"devpi は、 PyPI 互換の強力なサーバと PyPI プロクシキャッシュの機能を持ってい" +"て、 Python を使ったパッケージングやテスティングやリリース活動を推進するため" +"の補完的なコマンドラインツールを備えています。devpi は、また、閲覧と検索が可" +"能なwebインタフェイスも備えています。devpi は、 PyPI のミラーを作成する機能、" +"継承関係を持った複数の :term:`パッケージインデックス ` を扱う" +"機能、これらのインデックスの間の同期機能、インデックスの複製とフェイルオーバ" +"とパッケージのアップロードの機能を提供できます。" -#: ../source/news.rst:133 -msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +#: ../source/key_projects.rst:448 +msgid "dumb-pypi" +msgstr "dumb-pypi" + +#: ../source/key_projects.rst:450 +msgid "" +"`GitHub `__ | `PyPI `__" msgstr "" -"コアとなるメタデータの項に複数の電子メールアドレスの例を追加した。 (:pr:" -"`429`)" +"`GitHub `__ | `PyPI `__" -#: ../source/news.rst:134 -msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" -msgstr "test.pypi.org/legacy に \"legacy\" の説明を加えた。 (:pr:`426`)" +#: ../source/key_projects.rst:453 +msgid "" +"dumb-pypi is a simple :term:`package index ` static file site " +"generator, which then must be hosted by a static file webserver to become " +"the package index. It supports serving the hash, core-metadata, and yank-" +"status." +msgstr "" +"dumb-pypi は簡潔な :term:`パッケージインデックス ` の静的ファ" +"イルのサイトを構築するツールで、パッケージインデックスとして機能するためには" +"静的ファイルをサポートするウェブサーバにホストされていなければなりません。" +"ハッシュ、コアとなるメタデータ、そして yank ステータスをサポートしています。" -#: ../source/news.rst:137 -msgid "January 2018" -msgstr "2018年1月" +#: ../source/key_projects.rst:460 +msgid "enscons" +msgstr "enscons" -#: ../source/news.rst:139 -msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" -msgstr "PyPI にある分類子のリストへのリンクを追加した。 (:pr:`425`)" +#: ../source/key_projects.rst:462 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" +":gh:`ソースコード ` | :gh:`課題リスト ` | `PyPI `__" -#: ../source/news.rst:140 -msgid "Updated README.rst explanation. (:pr:`419`)" -msgstr "README.rst についての説明を更新した。 (:pr:`419`)" +#: ../source/key_projects.rst:466 +msgid "" +"Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" +"compatible source distributions and wheels without using distutils or " +"setuptools, including distributions with C extensions. Enscons has a " +"different architecture and philosophy than :ref:`distutils`. Rather than " +"adding build features to a Python packaging system, enscons adds Python " +"packaging to a general purpose build system. Enscons helps you to build " +"sdists that can be automatically built by :ref:`pip`, and wheels that are " +"independent of enscons." +msgstr "" +"Enscons は、 `SCons`_ に基礎を置く Python パッケージングツールです。 C 言語拡" +"張を含む配布物であっても distutils や setuptools を使うことなく :ref:`pip` 互" +"換のソースコード配布物や wheel をビルドすることができます。 Enscons の構造と" +"哲学は :ref:`distutils` のものとは異なります。 Python パッケージングシステム" +"にビルド機能を追加するのではなく、 enscons では汎用のビルドシステムに Python " +"パッケージング機能を追加しています。 Enscons は、 :ref:`pip` で自動的にビルド" +"された sdist や、enscons から独立した wheel をビルドすることを支援します。" -#: ../source/news.rst:143 -msgid "December 2017" -msgstr "2017年12月" +#: ../source/key_projects.rst:481 +msgid "Flask-Pypi-Proxy" +msgstr "Flask-Pypi-Proxy" -#: ../source/news.rst:145 +#: ../source/key_projects.rst:483 msgid "" -"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" msgstr "" -"ガイドやチュートリアルで :file:`~` を :file:`$HOME` に置き換えた。 (:pr:" -"`418`)" +"`説明文書 `__ | :gh:`GitHub " +"` | `PyPI `__" -#: ../source/news.rst:146 -msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +#: ../source/key_projects.rst:487 ../source/key_projects.rst:681 +#: ../source/key_projects.rst:740 +msgid "Not maintained, project archived" +msgstr "もはや保守されておらず、アーカイブされたプロジェクト" + +#: ../source/key_projects.rst:489 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." msgstr "" -"環境マーカとともにどのフィールドを使うことができるのかについて注記した。 (:" -"pr:`416`)" +"Flask-PyPI-Proxy は PyPI に対するキャッシュ付きのプロクシという形の :term:`" +"パッケージインデックス ` です。" -#: ../source/news.rst:147 -msgid "Updated Requires-Python section. (:pr:`414`)" -msgstr "Requires-Python の節を更新した。 (:pr:`414`)" +#: ../source/key_projects.rst:495 +msgid "Hashdist" +msgstr "Hashdist" -#: ../source/news.rst:148 -msgid "Added news page. (:pr:`404`)" -msgstr "ニュースのページを追加した。 (:pr:`404`)" +#: ../source/key_projects.rst:497 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`説明文書 `__ | `GitHub `__" + +#: ../source/key_projects.rst:500 +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 " +"doesn’t work”. The best way for Pythonistas to think about Hashdist may be a " +"more powerful hybrid of :ref:`virtualenv` and :ref:`buildout`. It is aimed " +"at solving the problem of installing scientific software, and making package " +"distribution stateless, cached, and branchable. It is used by some " +"researchers but has been lacking in maintenance since 2016." +msgstr "" +"Hashdist は、非特権ユーザソフトウェアの配布物をビルドするためのライブラリで" +"す。 Hashdist は、「Debian 技術が動作していない場合の Debian のような選択肢」" +"になろうとしています。 Python 支持者 (Pythonista) にとっては、 :ref:" +"`virtualenv` と :ref:`buildout` のより強力な混合物が Hashdist だと考えるのが" +"一番でしょう。科学計算分野のソフトウェアをインストールする際の問題を解決し、" +"パッケージ配布物をステートレスでキャッシュ可能かつ分岐可能にすることを目指し" +"ています。一部の研究者が使っていますが、2016 年以降は保守されていません。" -#: ../source/news.rst:151 -msgid "November 2017" -msgstr "2017年11月" +#: ../source/key_projects.rst:512 +msgid "Maturin" +msgstr "Maturin" -#: ../source/news.rst:153 +#: ../source/key_projects.rst:514 msgid "" -"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +"`Docs `__ | `GitHub `__" msgstr "" -"Pipenv を基盤とした依存関係の管理に関するチュートリアルを新たに追加した。 (:" -"pr:`402`)" +"`説明文書 `__ | `GitHub `__" -#: ../source/news.rst:154 +#: ../source/key_projects.rst:517 msgid "" -"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " -"current strategy. (:pr:`400`)" +"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 "" -"*パッケージバージョンの一元管理* のチュートリアルが pip の現在の戦略を反映す" -"るように更新した。 (:pr:`400`)" +"Maturin は Rust 拡張モジュール用のビルドバックエンドで、Rust で書かれていま" +"す。Windows ・ Linux ・ macOS および FreeBSD 上で python 3.7+ の wheel をビル" +"ドすることができ、それを PyPI にアップロードすることができ、また、 PyPy と " +"GraalPy に対する基本的なサポートもあります。" -#: ../source/news.rst:156 +#: ../source/key_projects.rst:525 +msgid "meson-python" +msgstr "meson-python" + +#: ../source/key_projects.rst:527 msgid "" -"Added documentation about the ``py_modules`` argument to ``setup``. (:pr:" -"`398`)" +"`Docs `__ | `GitHub `__" msgstr "" -"``setup`` に対する ``py_modules`` 引数について説明を追加した。 (:pr:`398`)" +"`説明文書 `__ | `GitHub " +"`__" -#: ../source/news.rst:157 -msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" -msgstr ":file:`manifest.in` 節での用語を簡素化した。 (:pr:`395`)" +#: ../source/key_projects.rst:530 +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 " +"package. It supports a wide variety of languages, including C, and is able " +"to fill the needs of most complex build configurations." +msgstr "" +"``meson-python`` は、 Meson_ ビルドシステムを使うビルドバックエンドです。これ" +"によって、 Python パッケージの作者が自分のパッケージ向けに Meson_ をビルドシ" +"ステムとして使うことを可能にします。これは C 言語を含む広範囲の言語をサポート" +"しており、最も複雑なビルド設定を記述することが可能になります。" -#: ../source/news.rst:160 -msgid "October 2017" -msgstr "2017年10月" +#: ../source/key_projects.rst:540 +msgid "multibuild" +msgstr "multibuild" -#: ../source/news.rst:162 -msgid "" -"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" -msgstr ":file:`entry_points.txt` ファイルの仕様を追記した。 (:pr:`398`)" +#: ../source/key_projects.rst:542 +msgid "`GitHub `__" +msgstr "`GitHub `__" -#: ../source/news.rst:163 +#: ../source/key_projects.rst:544 msgid "" -"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " -"(:pr:`385`)" +"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 "" -"``pip`` や ``virtualenv`` を用いてパッケージを管理するためのガイドを新設し" -"た。 (:pr:`385`)" +"Multibuild は、Linux ・ macOS 向けや (柔軟性は落ちるが) Windows 向けの " +"Python :term:`wheels ` をビルドしテストする一揃いの CI スクリプトで" +"す。 :ref:`cibuildwheel` も見てください。" -#: ../source/news.rst:164 -msgid "Split the specifications page into multiple pages. (:pr:`386`)" -msgstr "仕様のページを複数ページに分割した。 (:pr:`386`)" +#: ../source/key_projects.rst:550 +msgid "nginx_pypi_cache" +msgstr "nginx_pypi_cache" -#: ../source/news.rst:167 -msgid "September 2017" -msgstr "2017年9月" +#: ../source/key_projects.rst:552 +msgid ":gh:`GitHub `" +msgstr ":gh:`GitHub `" -#: ../source/news.rst:169 +#: ../source/key_projects.rst:554 msgid "" -"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. (:pr:" -"`379`)" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." msgstr "" -":file:`README.rst` を検証するために ``readme_renderer`` を使用することを推奨" -"するようにした。 (:pr:`379`)" - -#: ../source/news.rst:171 -msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" -msgstr "``--user-base`` オプションの使用を推奨するようにした。 (:pr:`374`)" +"nginx_pypi_cache は、 `nginx `_ を用いた :term:`パッ" +"ケージインデックス ` のキャッシュ機能付きプロクシです。" -#: ../source/news.rst:174 -msgid "August 2017" -msgstr "2017年8月" +#: ../source/key_projects.rst:560 +msgid "pdm" +msgstr "pdm" -#: ../source/news.rst:176 +#: ../source/key_projects.rst:562 msgid "" -"Added a new, experimental tutorial on installing packages using ``Pipenv``. " -"(:pr:`369`)" +"`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -"``Pipenv`` を用いてパッケージをインストールする方法について新たに試験的な" -"チュートリアルを追加した。 (:pr:`369`)" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:177 -msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" -msgstr "``TestPyPI`` を使う方法について新たにガイドを追加した。 (:pr:`366`)" +#: ../source/key_projects.rst:566 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" +"PDM は近代的な Python パッケージ管理ソフトです。 :pep:`621` で定義されている" +"形でプロジェクトのメタデータを :term:`pyproject.toml` に保存します。" -#: ../source/news.rst:178 -msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" -msgstr ":file:`pypi.org` を用語として追加した。 (:pr:`365`)" +#: ../source/key_projects.rst:574 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:181 -msgid "July 2017" -msgstr "2017年7月" +#: ../source/key_projects.rst:578 +msgid "" +"Pex is a tool for generating :file:`.pex` (Python EXecutable) files, " +"standalone Python environments in the spirit of :ref:`virtualenv`. PEX files " +"are :doc:`zipapps ` that make deployment of Python " +"applications as simple as ``cp``. A single PEX file can support multiple " +"target platforms and can be created from standard :ref:`pip`-resolvable " +"requirements, a lockfile generated with ``pex3 lock ...`` or even another " +"PEX. PEX files can optionally have tools embedded that support turning the " +"PEX file into a standard venv, graphing dependencies and more." +msgstr "" +"Pex は、 :ref:`virtualenv` を使った独立した Python 環境をに表現した :file:`." +"pex` (Python EXecutable) ファイルを生成するためのツールです。 PEX ファイル" +"は、 ``cp`` のような単純な Python アプリケーションをデプロイする :doc:" +"`zipapps ` です。単独の PEX ファイルで複数のターゲット" +"プラットフォームをサポートすることができ、標準の :ref:`pip` で解決できる要求" +"事項、つまり ``pex3 lock ...`` で生成されるロックファイルや別の PEX からで" +"あっても作成することができます。 PEX ファイルは、オプションとして PEX ファイ" +"ルを標準の venv に変換したり依存関係をグラフ化したり、あるいはもっと多くをサ" +"ポートするツールを内蔵することもできます。" -#: ../source/news.rst:183 -msgid "Added ``flit`` to the key projects list. (:pr:`358`)" -msgstr "``flit`` を鍵となるプロジェクト群のリストに追加した。 (:pr:`358`)" +#: ../source/key_projects.rst:590 +msgid "pip-tools" +msgstr "pip-tools" -#: ../source/news.rst:184 -msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" -msgstr "``enscons `` を鍵となるプロジェクト群のリストに追加した。 (:pr:`357`)" +#: ../source/key_projects.rst:592 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub " +"`__ | `PyPI `__" -#: ../source/news.rst:185 +#: ../source/key_projects.rst:596 msgid "" -"Updated this guide's ``readme`` with instructions on how to build the guide " -"locally. (:pr:`356`)" +"pip-tools is a suite of tools meant for Python system administrators and " +"release managers who particularly want to keep their builds deterministic " +"yet stay up to date with new versions of their dependencies. Users can " +"specify particular release of their dependencies via hash, conveniently make " +"a properly formatted list of requirements from information in other parts of " +"their program, update all dependencies (a feature :ref:`pip` currently does " +"not provide), and create layers of constraints for the program to obey." msgstr "" -"本ガイドの ``readme`` にローカル環境でこのガイドをビルドする方法を追加して更" -"新した。 (:pr:`356`)" +"pip-tools は、Python システムの管理者やリリースマネージャで、特にビルドが必ず" +"できるように保ちたいけれども依存先の新バージョンに追随して最新の状態にもして" +"おきたいという人々のための一揃いのツール群です。ユーザはハッシュ値を与えるこ" +"とで依存先の特定のリリースを指定することや、そのプログラムの他の部分にある情" +"報から適切な書式の requirements を簡単に作成すること、すべての依存先を更新す" +"ること (これは現時点の :ref:`pip` にはない機能です) 、プログラムが従うべき制" +"約条件の層を作成することができます。" -#: ../source/news.rst:186 +#: ../source/key_projects.rst:608 +msgid "pip2pi" +msgstr "pip2pi" + +#: ../source/key_projects.rst:610 msgid "" -"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " -"pypi.org. (:pr:`354`)" +":gh:`GitHub ` | `PyPI `__" msgstr "" -"ホームページにpypi.org に関する注記を加えることで、新しい ``TestPyPI`` の " -"URL がより目立つようにした。 (:pr:`354`)" +":gh:`GitHub ` | `PyPI `__" -#: ../source/news.rst:187 +#: ../source/key_projects.rst:613 msgid "" -"Added a note about the removal of the explicit registration API. (:pr:`347`)" -msgstr "明示的な登録を行う API の削除について注記を追加した。 (:pr:`347`)" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" +"pip2pi は、特定のパッケージ群が手動で同期される :term:`パッケージインデック" +"ス ` です。" -#: ../source/news.rst:190 -msgid "June 2017" -msgstr "2017年6月" +#: ../source/key_projects.rst:619 +msgid "piwheels" +msgstr "piwheels" -#: ../source/news.rst:192 -msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +#: ../source/key_projects.rst:621 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" +"`Web サイト `__ | :doc:`説明文書 ` | `GitHub `__" + +#: ../source/key_projects.rst:625 +msgid "" +"piwheels is a website, and software underpinning it, that fetches source " +"code distribution packages from PyPI and compiles them into binary wheels " +"that are optimized for installation onto Raspberry Pi computers. Raspberry " +"Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -":file:`PyPI.org` へのアップロード方法の変更について説明を追加した。 (:pr:" -"`339`)" +"piwheels は、ソースコード配布物パッケージを PyPI から取得して Raspberry Pi 計" +"算機へのインストールに最適化されたバイナリ wheel ファイルにコンパイルするよう" +"な Web サイトであり、それを支えるソフトウェアです。 Raspberry Pi OS では、 " +"pip が PyPI に加えて piwheel.org を追加のインデックスとして使うように予め設定" +"されています。" -#: ../source/news.rst:193 -msgid "Added documentation for ``python_requires``. (:pr:`338`)" -msgstr "``python_requires`` について説明を追加した。 (:pr:`338`)" +#: ../source/key_projects.rst:634 +msgid "poetry" +msgstr "poetry" -#: ../source/news.rst:194 +#: ../source/key_projects.rst:636 msgid "" -"Added a note about PyPI migration in the *Tool Recommendations* tutorial. (:" -"pr:`335`)" +"`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -"*推奨されるツール* のチュートリアル内で PyPI の移転に関する注記を追加した。 " -"(:pr:`335`)" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:195 +#: ../source/key_projects.rst:640 msgid "" -"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +"poetry is a command-line tool to handle dependency installation and " +"isolation as well as building and packaging of Python packages. It uses " +"``pyproject.toml`` and, instead of depending on the resolver functionality " +"within :ref:`pip`, provides its own dependency resolver. It attempts to " +"speed users' experience of installation and dependency resolution by locally " +"caching metadata about dependencies." msgstr "" -":file:`manifest.in` が wheel には影響を与えないことを注記した。 (:pr:`332`)" - -#: ../source/news.rst:196 -msgid "Added a license section to the distributing guide. (:pr:`331`)" -msgstr "配布ガイドにライセンスの節を追加した。 (:pr:`331`)" - -#: ../source/news.rst:197 -msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" -msgstr "``name`` 引数に関する節を拡充した。 (:pr:`329`)" - -#: ../source/news.rst:198 -msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" -msgstr "ランディングページを調整した。 (:pr:`327`, :pr:`326`, :pr:`324`)" - -#: ../source/news.rst:199 -msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" -msgstr "Sphinx 1.6.2 にバージョンを上げた。 (:pr:`323`)" - -#: ../source/news.rst:200 -msgid "Switched to the PyPA theme. (:pr:`305`)" -msgstr "PyPA のテーマに切り替えた。 (:pr:`305`)" - -#: ../source/news.rst:201 -msgid "Re-organized the documentation into the new structure. (:pr:`318`)" -msgstr "説明文書を新しい構造に再編成した。 (:pr:`318`)" +"poetry は、 Python パッケージのビルドやパッケージングに加えて、依存先のインス" +"トールや隔離を取り扱うコマンドラインのツールです。 :ref:`pip` に含まれる解決" +"機能に依存する代わりに ``pyproject.toml`` を使って自分自身の依存関係解決機能" +"を提供します。依存関係に関するメタデータをローカルにキャッシュすることでイン" +"ストールや依存関係解決のユーザ体験を高速化しようとしています。" -#: ../source/news.rst:204 -msgid "May 2017" -msgstr "2017年5月" +#: ../source/key_projects.rst:650 +msgid "proxpi" +msgstr "proxpi" -#: ../source/news.rst:206 +#: ../source/key_projects.rst:652 msgid "" -"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" -msgstr "``Description-Content-Type`` 欄について説明を追加した。 (:pr:`258`)" - -#: ../source/news.rst:207 -msgid "Added contributor and style guide. (:pr:`307`)" -msgstr "貢献者向けのガイドとスタイルガイドを追加した。 (:pr:`307`)" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" -#: ../source/news.rst:208 +#: ../source/key_projects.rst:655 msgid "" -"Documented ``pip`` and ``easy_install``'s differences for per-project " -"indexes. (:pr:`233`)" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." msgstr "" -"プロジェクト単位の索引における ``pip`` と ``easy_install`` の差異について説明" -"した。 (:pr:`233`)" - -#: ../source/news.rst:211 -msgid "April 2017" -msgstr "2017年4月" +"proxpi は、PyPI や他のインデックスをキャッシュ付きでプロクシする単純な :term:" +"`パッケージインデックス ` です。" -#: ../source/news.rst:213 -msgid "Added travis configuration for testing pull requests. (:pr:`300`)" -msgstr "プルリクエストの試験のための travis 設定を追記した。 (:pr:`300`)" +#: ../source/key_projects.rst:661 +msgid "Pulp-python" +msgstr "Pulp-python" -#: ../source/news.rst:214 +#: ../source/key_projects.rst:663 msgid "" -"Mentioned the requirement of the ``wheel`` package for creating wheels (:pr:" -"`299`)" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" msgstr "" -"wheel ファイルを生成するための ``wheel`` パッケージへの要求条件に言及するよう" -"にした。 (:pr:`299`)" +"`説明文書 `__ | :gh:`GitHub ` | `PyPI `__" -#: ../source/news.rst:215 +#: ../source/key_projects.rst:667 msgid "" -"Removed the ``twine register`` reference in the *Distributing Packages* " -"tutorial. (:pr:`271`)" +"Pulp-python is the Python :term:`package index ` plugin for " +"`Pulp `_. Pulp-python supports mirrors backed by " +"local or `AWS S3`_, package upload, and proxying to multiple package indexes." msgstr "" -"*パッケージを配布する* チュートリアルにおいて ``twine register`` への参照を削" -"除した。 (:pr:`271`)" +"Pulp-python は、 `Pulp ` 向けの Python :term:`パッ" +"ケージインデックス ` プラグインです。 Pulp-python は、ローカル" +"か `AWS S3`_ にファイルを置くミラー機能や、複数のパッケージインデックスへのプ" +"ロクシ機能をサポートします。" -#: ../source/news.rst:216 -msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" -msgstr "プラグインの検索に関する話題を追加した。 (:pr:`294`, :pr:`296`)" +#: ../source/key_projects.rst:675 +msgid "PyPI Cloud" +msgstr "PyPI クラウド" -#: ../source/news.rst:217 -msgid "Added a topic on namespace packages. (:pr:`290`)" -msgstr "名前空間パッケージの話題を追加した。 (:pr:`290`)" +#: ../source/key_projects.rst:677 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`説明文書 `__ | :gh:`GitHub ` | `PyPI `__" -#: ../source/news.rst:218 +#: ../source/key_projects.rst:683 msgid "" -"Added documentation explaining prominently how to install ``pip`` in ``/usr/" -"local``. (:pr:`230`)" +"PyPI Cloud is a :term:`package index ` server, backed by `AWS " +"S3`_ or another cloud storage service, or local files. PyPI Cloud supports " +"redirect/cached proxying for PyPI, as well as authentication and " +"authorisation." msgstr "" -"``pip`` を ``/usr/local`` にインストールする方法を目立つように説明する文書を" -"追加した。 (:pr:`230`)" +"PyPI クラウドは、`AWS S3`_ や他のクラウドストレージサービス、あるいはローカル" +"のファイル群で裏打ちされた :term:`パッケージインデックス ` で" +"す。PyPI クラウドは、認証や認可と同様に PyPI に対するリダイレクト機能やプロク" +"シ機能をサポートします。" -#: ../source/news.rst:219 +#: ../source/key_projects.rst:691 +msgid "pypiprivate" +msgstr "pypiprivate" + +#: ../source/key_projects.rst:693 msgid "" -"Updated development mode documentation to mention that order of local " -"packages matters. (:pr:`208`)" +":gh:`GitHub ` | `PyPI `__" msgstr "" -"開発モードの説明文書を更新して、ローカルパッケージの記入順に意味があることに" -"言及するようにした。 (:pr:`208`)" +":gh:`GitHub ` | `PyPI `__" -#: ../source/news.rst:220 +#: ../source/key_projects.rst:696 msgid "" -"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " -"projects (:pr:`239`)" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as a :" +"term:`package index `." msgstr "" -"ホストしているプロジェクトのところで readthedocs の引っ越しに合わせてリンク" -"を ``.org`` から ``.io`` に変更した。 (:pr:`239`)" +"pypiprivate は、 :term:`パッケージインデックス ` としてローカ" +"ルの (または `AWS S3`_ でホストされた) パッケージディレクトリを提供します。" -#: ../source/news.rst:221 +#: ../source/key_projects.rst:702 +msgid "pypiserver" +msgstr "pypiserver" + +#: ../source/key_projects.rst:704 msgid "" -"Swapped order of :file:`setup.py` arguments for the upload command, as order " -"is significant. (:pr:`260`)" +"`GitHub `__ | `PyPI `__" msgstr "" -"順序が意味を持つので、アップロードコマンドの :file:`setup.py` の引数の順序を" -"入れ替えた。 (:pr:`260`)" +"`GitHub `__ | `PyPI `__" -#: ../source/news.rst:223 +#: ../source/key_projects.rst:707 msgid "" -"Explained how to install from unsupported sources using a helper " -"application. (:pr:`289`)" +"pypiserver is a minimalist application that serves as a private Python :term:" +"`package index ` (from a local directory) within " +"organizations, implementing a simple API and browser interface. You can " +"upload private packages using standard upload tools, and users can download " +"and install them with :ref:`pip`, without publishing them publicly. " +"Organizations who use pypiserver usually download packages both from " +"pypiserver and from PyPI." msgstr "" -"サポートされていないソースからヘルパーアプリケーションを用いてインストールす" -"る方法について説明した。 (:pr:`289`)" +"pypiserver は、単純な API とブラウザ向けのインタフェイスだけを実装した (ロー" +"カルディレクトリ上の) 組織内部向けプライベート Python :term:`パッケージイン" +"デックス ` として振る舞う「小さいことは良いことだ」主義者のア" +"プリケーションです。公衆向けに公開することなく標準のツールを使って外部非公開" +"のパッケージをアップロードすることもできますし、それを `pip` でダウンロード・" +"インストールすることもできます。 pypiserver を用いる組織では、通常は " +"pypiserver と PyPI の両方からパッケージをダウンロードします。" -#: ../source/news.rst:227 -msgid "March 2017" -msgstr "2017年3月" +#: ../source/key_projects.rst:718 +msgid "PyScaffold" +msgstr "PyScaffold" -#: ../source/news.rst:229 -msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +#: ../source/key_projects.rst:720 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -"*プラットフォームWheels* の項で ``manylinux1`` をカバーした。 (:pr:`283`)" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/news.rst:232 -msgid "February 2017" -msgstr "2017年2月" +#: ../source/key_projects.rst:724 +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 " +"sane default configurations for established tools (such as :ref:" +"`setuptools`, pytest_ and Sphinx_) to provide a productive environment so " +"developers can start coding right away. PyScaffold can also be used with " +"existing projects to make packaging easier." +msgstr "" +"PyScaffold は、Python パッケージが PyPI で共有できて :ref:`pip` でインストー" +"ルできるように初期設定を行うプロジェクトジェネレータです。定評のあるツール (:" +"ref:`setuptools` や pytest_ や Sphinx_) 用に穏当なデフォルト設定を与えること" +"で、開発者がすぐにコードを書き始められるような生産的な環境を提供します。 " +"PyScaffold は、また、既存のプロジェクトにおいてもパッケージングをより簡単にす" +"るために使用することができます。" -#: ../source/news.rst:234 -msgid "Added :pep:`518`. (:pr:`281`)" -msgstr ":pep:`518` を追加した。 (:pr:`281`)" +#: ../source/key_projects.rst:735 +msgid "pywharf" +msgstr "pywharf" -#: ../source/overview.rst:3 -msgid "Overview of Python Packaging" -msgstr "Python におけるパッケージングに関する概要" +#: ../source/key_projects.rst:737 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" -#: ../source/overview.rst:7 +#: ../source/key_projects.rst:742 msgid "" -"As a general-purpose programming language, Python is designed to be used in " -"many ways. You can build web sites or industrial robots or a game for your " -"friends to play, and much more, all using the same core technology." +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." msgstr "" -"汎用プログラミング言語として Python は数多くの用途に使えるように設計されてい" -"ます。ウェブサイト構築にも産業用ロボットにもあなたが友達と一緒に遊ぶゲームに" -"ももっと他の用途にも、同じコア技術が使えるのです。" +"pywharf は、ローカルから、もしくは `GitHub `_ からファイ" +"ルを提供する :term:`パッケージインデックス ` です。" -#: ../source/overview.rst:12 +#: ../source/key_projects.rst:748 +msgid "scikit-build" +msgstr "scikit-build" + +#: ../source/key_projects.rst:750 msgid "" -"Python's flexibility is why the first step in every Python project must be " -"to think about the project's audience and the corresponding environment " -"where the project will run. It might seem strange to think about packaging " -"before writing code, but this process does wonders for avoiding future " -"headaches." +"`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -"Python は自由度が高いので、プロジェクトの利用者について、また、それに対応して" -"プロジェクトが動作するであろう環境について、すべての Python プロジェクトにお" -"いて最初に考えなければなりません。コードを書く前にパッケージングについて考え" -"ておくというのは奇妙に見えるかもしれませんが、この作業こそが将来の頭痛の種を" -"摘み取るという驚くべきことを起こすのです。" +"`説明文書 `__ | `GitHub " +"`__ | `PyPI `__" -#: ../source/overview.rst:18 +#: ../source/key_projects.rst:754 msgid "" -"This overview provides a general-purpose decision tree for reasoning about " -"Python's plethora of packaging options. Read on to choose the best " -"technology for your next project." +"Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" +"Fortran/Cython extensions It 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)." msgstr "" -"この概要文書は、 Python の過剰とも言える多数のパッケージング手段からどれを選" -"択するかについての汎用の決定木を提供します。読み進めて、あなたの次のプロジェ" -"クトにとっての最適解を選んでください。" +"Scikit-build は、C/C++/Fortran/Cython で書かれた拡張をビルドする CPython のた" +"めの :ref:`setuptools` ラッパです。追加のコンパイラやビルドシステムやクロスコ" +"ンパイルに対するより良いサポートを提供するため、また、関連するビルドで要求さ" +"れるライブラリなど の位置を特定するために `cmake " +"`__ (PyPI にあります) を使用します。大きなプ" +"ロジェクトのビルドの速度を増したり並列化したりするために、ユーザは `ninja " +"`___ (これも PyPI にあります) をインストール" +"することができます。" -#: ../source/overview.rst:23 -msgid "Thinking about deployment" -msgstr "デプロイメントについて検討する" +#: ../source/key_projects.rst:765 +msgid "scikit-build-core" +msgstr "scikit-build-core" -#: ../source/overview.rst:25 +#: ../source/key_projects.rst:767 msgid "" -"Packages exist to be installed (or *deployed*), so before you package " -"anything, you'll want to have some answers to the deployment questions below:" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" msgstr "" -"パッケージはインストールされる(あるいは *配置* される)ために存在しているの" -"で、なにかをパッケージ化する前に次のような配置のための質問にいくらかの答えを" -"持っておきたいと思うでしょう:" +"`説明文書 `__ | `GitHub " +"`__ | `PyPI `__" -#: ../source/overview.rst:29 +#: ../source/key_projects.rst:771 msgid "" -"Who are your software's users? Will your software be installed by other " -"developers doing software development, operations people in a datacenter, or " -"a less software-savvy group?" +"Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " +"extensions. It enables users to write extensions with `cmake `__ (available on PyPI) to provide better support for " +"additional compilers, build systems, cross compilation, and locating " +"dependencies and their associated build requirements. CMake/Ninja are " +"automatically downloaded from PyPI if not available on the system." msgstr "" -"あなたのソフトウェアのユーザはどんな人たちでしょうか？ソフトウェアを開発する" -"他の開発者たちがインストールするのでしょうか、データセンタでオペレーションを" -"する人々でしょうか、それとも、ソフトウェアを知り尽くしているとは言えないよう" -"な人たちでしょうか？" +"Scikit-build-core は、CPython C/C++/Fortran/Cython による拡張モジュールのため" +"のビルドバックエンドです。追加のコンパイラやビルドシステムやクロスコンパイ" +"ル、また、依存関係とそれに付随するビルド時の要求事項を解決する点でより良いサ" +"ポートを提供するために、ユーザが `cmake `__ " +"(PyPI から利用可能) を使って拡張を書くことができるようにします。 CMake/Ninja " +"は、もしシステム上に利用可能なものがなければ、 PyPI から自動的にダウンロード" +"されます。" -#: ../source/overview.rst:32 +#: ../source/key_projects.rst:781 +msgid "shiv" +msgstr "shiv" + +#: ../source/key_projects.rst:783 msgid "" -"Is your software intended to run on servers, desktops, mobile clients " -"(phones, tablets, etc.), or embedded in dedicated devices?" +"`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -"あなたのソフトウェアは、サーバ上で走らせることを想定していますか、それとも、" -"デスクトップ、モバイル端末 (携帯電話やタブレット端末等) 、あるいは、専用端末" -"に組み込む形で？" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/overview.rst:34 +#: ../source/key_projects.rst:787 msgid "" -"Is your software installed individually, or in large deployment batches?" +"shiv is a command line utility for building fully self contained Python " +"zipapps as outlined in :pep:`441`, but with all their dependencies included. " +"Its primary goal is making distributing Python applications and command line " +"tools fast & easy." msgstr "" -"あなたのソフトウェアは、単独でインストールされるものですか、それとも、巨大な" -"デプロイメントバッチの一部として？" +"shiv は、 :pep:`441` に概要が示されている完全自己完結型 Python zipapp である" +"が必要な依存先をすべて内包したものをビルドするためのコマンドラインユーティリ" +"ティです。このツールの第一の目標は、Python アプリケーションとコマンドライン" +"ツールを素早く簡便に配布できるようにすることです。" -#: ../source/overview.rst:36 +#: ../source/key_projects.rst:795 +msgid "simpleindex" +msgstr "simpleindex" + +#: ../source/key_projects.rst:797 msgid "" -"Packaging is all about target environment and deployment experience. There " -"are many answers to the questions above and each combination of " -"circumstances has its own solutions. With this information, the following " -"overview will guide you to the packaging technologies best suited to your " -"project." +":gh:`GitHub ` | `PyPI `__" msgstr "" -"パッケージングとは、インストール先となる環境と配置(デプロイ)経験に関わるすべ" -"てのことです。上に述べた質問には多くの回答があり、それぞれの事情の組み合わせ" -"ごとに解決策が存在します。この情報とともに、以下の概要説明の中で、あなたのプ" -"ロジェクトに最適なパッケージング技術についてご案内します。" - -#: ../source/overview.rst:43 -msgid "Packaging Python libraries and tools" -msgstr "Python のライブラリやツールをパッケージングする" +":gh:`GitHub ` | `PyPI `__" -#: ../source/overview.rst:45 +#: ../source/key_projects.rst:800 msgid "" -"You may have heard about PyPI, ``setup.py``, and ``wheel`` files. These are " -"just a few of the tools Python's ecosystem provides for distributing Python " -"code to developers, which you can read about in :doc:`guides/distributing-" -"packages-using-setuptools`." +"simpleindex is a :term:`package index ` which routes URLs to " +"multiple package indexes (including PyPI), serves local (or cloud-hosted, " +"for example `AWS S3`_, with a custom plugin) directories of packages, and " +"supports custom plugins." msgstr "" -"PyPI や ``setup.py`` 、 ``wheel`` ファイルについて聞いたことがあるかもしれま" -"せん。これらは Python のソースコードを開発者に配布するための Python エコシス" -"テムのほんの一部で、これらについては :doc:`guides/distributing-packages-" -"using-setuptools` に説明があります。" +"simple index は、 URL を (PyPI を含む) 複数のパッケージインデックスに振り分" +"け、ローカルの (または、カスタムプラグインを使って例えば `AWS S3`_ のようなク" +"ラウドにホストされた) パッケージディレクトリからファイルを提供し、カスタムプ" +"ラグインをサポートしている :term:`パッケージインデックス ` で" +"す。" -#: ../source/overview.rst:50 +#: ../source/key_projects.rst:810 msgid "" -"The following approaches to packaging are meant for libraries and tools used " -"by technical audience in a development setting. If you're looking for ways " -"to package Python for a non-technical audience and/or a production setting, " -"skip ahead to :ref:`packaging-applications`." +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" msgstr "" -"パッケージングに関する以下のアプローチは、開発環境における技術に明るい聞き手" -"が用いるライブラリやツールを念頭に置いています。技術にあまり明るくない聞き手" -"向けに Python をパッケージする方法や、製品使用環境での方法を探している場合" -"は、 :ref:`アプリケーションをパッケージングする` まで飛ばしてください。" +":doc:`説明文書 ` | `GitHub `__ " +"| `論文 `__ | `スライド `__" -#: ../source/overview.rst:56 -msgid "Python modules" -msgstr "Python モジュール" +#: ../source/key_projects.rst:815 +msgid "" +"A flexible package manager designed to support multiple versions, " +"configurations, platforms, and compilers. Spack is like Homebrew, but " +"packages are written in Python and parameterized to allow easy swapping of " +"compilers, library versions, build options, etc. Arbitrarily many versions " +"of packages can coexist on the same system. Spack was designed for rapidly " +"building high performance scientific applications on clusters and " +"supercomputers." +msgstr "" +"(spack は) 複数のバージョン・設定・プラットフォーム・コンパイラをサポートする" +"ように設計された自由度の高いパッケージマネージャです。 Spack は Homebrew に似" +"ていますが、Python で書かれていてコンパイラやライブラリのバージョン、ビルドオ" +"プションなどが簡単に入れ替えることができるようにパラメータ化されています。同" +"一のシステムの中に任意のバージョンのパッケージをいくつも同居させることができ" +"ます。 Spack は、元々はクラスタ構成のコンピュータ群やスーパーコンピュータの上" +"で科学分野の高パフォーマンスアプリケーションを素早くビルドするために設計され" +"ました。" -#: ../source/overview.rst:58 +#: ../source/key_projects.rst:823 msgid "" -"A Python file, provided it only relies on the standard library, can be " -"redistributed and reused. You will also need to ensure it's written for the " -"right version of Python, and only relies on the standard library." +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." msgstr "" -"標準ライブラリだけに依存している Python のファイルは、再配布して再利用するこ" -"とができます。他には正しいバージョンの Python 用に書かれていることと、標準ラ" -"イブラリだけに依存していることを確実にしておけば良いでしょう。" +"Spack は (まだ) PyPI にありませんが、 GitHub からクローンした直後にインストー" +"ル作業なしで使用できます。" -#: ../source/overview.rst:63 +#: ../source/key_projects.rst:829 +msgid "zest.releaser" +msgstr "zest.releaser" + +#: ../source/key_projects.rst:831 msgid "" -"This is great for sharing simple scripts and snippets between people who " -"both have compatible Python versions (such as via email, StackOverflow, or " -"GitHub gists). There are even some entire Python libraries that offer this " -"as an option, such as :doc:`bottle.py` and :doc:`boltons " -"`." +"`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -"この方法は、単純なスクリプトやスニペットを互換性のあるバージョンの Python を" -"持っている人たちどうしで (電子メールや StackOverflow や GitHub gists などで) " -"共有するには優れた方法です。例えば :doc:`bottle.py ` や :" -"doc:`boltons ` のように、 Python ライブラリ全体をこのや" -"り方で共有することをオプションの一つとして提供しているものさえあります。" +"`説明文書 `__ | `GitHub " +"`__ | `PyPI `__" -#: ../source/overview.rst:70 +#: ../source/key_projects.rst:835 msgid "" -"However, this pattern won't scale for projects that consist of multiple " -"files, need additional libraries, or need a specific version of Python, " -"hence the options below." +"``zest.releaser`` is a Python package release tool providing an abstraction " +"layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " +"automate incrementing package version numbers, updating changelogs, tagging " +"releases in source control, and uploading new packages to PyPI." msgstr "" -"しかしながら、複数のファイルで構成されるプロジェクトや追加のライブラリを必要" -"とするもの、また、特定バージョンの Python を必要とするものには適用できず、そ" -"の場合には下のようなやり方が選択肢になります。" +"``zest.releaser`` は、 :ref:`twine` の上に抽象レイヤを提供する Python パッ" +"ケージのリリースツールです。 Python 開発者は ``zest.releaser`` を使ってパッ" +"ケージバージョンを増加させたり、変更履歴 (Changelog) を更新したり、ソースコー" +"ド管理の側でリリースタグを挿入したり、新しいパッケージを PyPI にアップロード" +"することを自動化することができます。" -#: ../source/overview.rst:75 -msgid "Python source distributions" -msgstr "Python ソースコード配布物" +#: ../source/key_projects.rst:842 +msgid "Standard Library Projects" +msgstr "標準ライブラリ内のプロジェクト群" -#: ../source/overview.rst:77 -msgid "" -"If your code consists of multiple Python files, it's usually organized into " -"a directory structure. Any directory containing Python files can comprise " -"an :term:`Import Package`." -msgstr "" -"あなたのソースコードが複数の Python ファイルでできているなら、ディレクトリ構" -"造の中に整理してあるのが普通です。 Python ファイルを置いてあるディレクトリな" -"らどれでも、 :term:`パッケージインポート ` ができるはずです。" +#: ../source/key_projects.rst:847 +msgid "ensurepip" +msgstr "ensurepip" -#: ../source/overview.rst:81 +#: ../source/key_projects.rst:849 msgid "" -"Because packages consist of multiple files, they are harder to distribute. " -"Most protocols support transferring only one file at a time (when was the " -"last time you clicked a link and it downloaded multiple files?). It's easier " -"to get incomplete transfers, and harder to guarantee code integrity at the " -"destination." +"`Docs `__ | `Issues " +"`__" msgstr "" -"パッケージは複数のファイルで構成されるので、その配布がやや難しくなります。ほ" -"とんどのプロトコルではたった一個のファイルしか一度に送ることができません (リ" -"ンクをクリックしたら複数のファイルをダウンロードしたことあります？)。不完全な" -"転送になってしまうことは容易く、送り先でソースコードの完全性を保証することは" -"困難です。" +"`説明文書 `__ | `課題リス" +"ト `__" -#: ../source/overview.rst:87 +#: ../source/key_projects.rst:852 msgid "" -"So long as your code contains nothing but pure Python code, and you know " -"your deployment environment supports your version of Python, then you can " -"use Python's native packaging tools to create a *source* :term:`Distribution " -"Package`, or *sdist* for short." +"A package in the Python Standard Library that provides support for " +"bootstrapping :ref:`pip` into an existing Python installation or virtual " +"environment. In most cases, end users won't use this module, but rather it " +"will be used during the build of the Python distribution." msgstr "" -"あなたのソースコードが純粋な Python コード以外は何も含んでいない間は、そし" -"て、配置先の環境であなたが想定しているバージョンの Python が動作することを" -"知っていれば、 Python 由来のパッケージングツールを使って *ソースコード* :" -"term:`配布パッケージ ` もしくは 短縮系で*sdist* を使え" -"ば良いでしょう。" +"このパッケージはPython の標準ライブラリ内のパッケージで、既存のインストール済" +"み Python 環境や仮想環境に :ref:`pip` を組み込むためのサポートを提供します。" +"ほとんどの場合にはエンドユーザがこのモジュールを使うことはなく、どちらかと言" +"えば Python 配布物のビルドの際に使われるでしょう。" -#: ../source/overview.rst:92 +#: ../source/key_projects.rst:860 +msgid "http.server" +msgstr "http.server" + +#: ../source/key_projects.rst:862 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 go to the :ref:`source-distribution-" -"format` specification to learn more." +":doc:`Docs ` | :gh:`Issues `" msgstr "" -"Python の *sdists* は圧縮済みのアーカイブ (``.tar.gz`` ファイル) で、ひとつか" -"それ以上のパッケージないしモジュールを内包しています。もしあなたのソースコー" -"ドが純粋に Python だけで書かれていて、他の Python パッケージに依存しているだ" -"けなら、 :ref:`ソースコード配布物フォーマット ` " -"仕様を見ればもっと詳しく知ることができます。" +":doc:`説明文書 ` | :gh:`課題リスト `" -#: ../source/overview.rst:97 +#: ../source/key_projects.rst:865 msgid "" -"If you rely on any non-Python code, or non-Python packages (such as `libxml2 " -"`_ in the case of `lxml `_, or BLAS libraries in the case of `numpy `_), you will need to use the format detailed in the next " -"section, which also has many advantages for pure-Python libraries." +"A package and command-line interface which can host a directory as a " +"website, for example as a :term:`package index ` (see :ref:" +"`Hosting your Own Simple Repository`)." msgstr "" -"もし非 Python のソースコード、あるいは、非 Python のパッケージ (`lxml " -"`_ における`libxml2 `_ や、`numpy `_ における " -"BLAS ライブラリなど) に依存しているなら、純 Python で書かれたライブラリにとっ" -"ても多くの利点がある、次の節で詳細に説明されるフォーマットを使う必要があるで" -"しょう。" +"ウェブサイトとして、つまり例えば :term:`パッケージインデックス ` として、ディレクトリを扱うことができるパッケージとコマンドラインイン" +"タフェース (:ref:`自分用のシンプルなリポジトリをホストする ` を参照してください) 。" -#: ../source/overview.rst:104 +#: ../source/key_projects.rst:872 +msgid "venv" +msgstr "venv" + +#: ../source/key_projects.rst:874 msgid "" -"Python and PyPI support multiple distributions providing different " -"implementations of the same package. For instance the unmaintained-but-" -"seminal `PIL distribution `_ provides the PIL " -"package, and so does `Pillow `_, an " -"actively-maintained fork of PIL!" +"`Docs `__ | `Issues `__" msgstr "" -"Python と PyPI は、同一のパッケージの異なる実装を提供する複数の配布物をサポー" -"トしています。例えば、もはや保守されてはいないが先駆的で重要な `PIL 配布物 " -"`_ が PIL パッケージを提供しているし、 PIL か" -"らフォークして今も活発に保守されている `Pillow `_ も同様です！" +"`説明文書 `__ | `課題リスト " +"`__" -#: ../source/overview.rst:111 +#: ../source/key_projects.rst:877 msgid "" -"This Python packaging superpower makes it possible for Pillow to be a drop-" -"in replacement for PIL, just by changing your project's ``install_requires`` " -"or ``requirements.txt``." +"A package in the Python Standard Library (starting with Python 3.3) for " +"creating :term:`Virtual Environments `. For more " +"information, see the section on :ref:`Creating and using Virtual " +"Environments`." msgstr "" -"この Python パッケージングの素晴らしいパワーで、あなたのプロジェクトの " -"``install_requires`` か ``requirements.txt`` を変更するだけで Pillow が PIL " -"に対して単純に入れ替えるだけで済む代替物になっているのです。" +"(Python 3.3 から始まる) Python の標準ライブラリに存在する :term:`仮想環境 " +"` を生成するためのパッケージ。更なる情報については :ref:" +"`仮想環境を作って使う ` を見てくださ" +"い。" -#: ../source/overview.rst:116 -msgid "Python binary distributions" -msgstr "Python バイナリ配布物" +#: ../source/news.rst:2 +msgid "News" +msgstr "ニュース" -#: ../source/overview.rst:118 +#: ../source/news.rst:4 msgid "" -"So much of Python's practical power comes from its ability to integrate with " -"the software ecosystem, in particular libraries written in C, C++, Fortran, " -"Rust, and other languages." +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." msgstr "" -"Python の実際的な力の多くは、ソフトウェアのエコシステム、とりわけ C ・ C++ " -"・ Fortran ・ Rust ・その他の言語で書かれたライブラリと統合できる能力からもた" -"らされます。" +"この文書は現在では更新されていません。以前は、Python パッケージングでの変更点" +"をハイライトしていました。" -#: ../source/overview.rst:122 -msgid "" -"Not all developers have the right tools or experiences to build these " -"components written in these compiled languages, so Python created the :term:" -"`Wheel`, a package format designed to ship libraries with compiled " -"artifacts. In fact, Python's package installer, ``pip``, always prefers " -"wheels because installation is always faster, so even pure-Python packages " -"work better with wheels." +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "2019年9月" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" msgstr "" -"このようなコンパイルを必要とする言語で書かれた部品をビルドするのに適切なツー" -"ルや経験をすべての開発者が持っているわけではないので、ライブラリをコンパイル" -"済みの状態で出荷するように設計された :term:`Wheel` を Python は作りました。実" -"際に、 Python のパッケージインストーラである ``pip`` は、インストールが素早く" -"できるので常に wheel ファイルを選好するし、純 Python のパッケージでさえも " -"wheel ファイルの方がうまく動作します。" +"GitHub Actions を経由して配布物を公開するためのガイドを追加。 (:pr:`647`)" -#: ../source/overview.rst:129 -msgid "" -"Binary distributions are best when they come with source distributions to " -"match. Even if you don't upload wheels of your code for every operating " -"system, by uploading the sdist, you're enabling users of other platforms to " -"still build it for themselves. Default to publishing both sdist and wheel " -"archives together, *unless* you're creating artifacts for a very specific " -"use case where you know the recipient only needs one or the other." +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "2019年8月" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" msgstr "" -"バイナリ配布物は、対応するソースコード配布物と一緒に配布されるのが最良です。 " -"あらゆるオペレーティングシステム用のソースコードの wheel ファイルをアップロー" -"ドしていないとしても、sdist をアップロードすることで他のプラットフォームの" -"ユーザたちがビルドすることができるかもしれません。あなたが極めて特殊なユース" -"ケース向けにプログラムを作成していて、受け取る人たちがいずれか一方しか必要と" -"しないことを熟知しているので *ない限り* 、 sdist と wheel の両方を一緒に公開" -"することをデフォルトにしてください。" +"pipx をインストールする際に :file:`python3 -m` を使うように更新。 (:pr:`631`)" -#: ../source/overview.rst:137 -msgid "" -"Python and PyPI make it easy to upload both wheels and sdists together. Just " -"follow the :doc:`tutorials/packaging-projects` tutorial." +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "2019年7月" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "すべての PEP 番号を :pep: 役割の形にした。 (:pr:`629`)" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" msgstr "" -"Python と PyPI を使えば、wheel ファイルと sdist ファイルを一緒にアップロード" -"するのが簡単になります。 :doc:`tutoeials/packaging-projects` のチュートリアル" -"に従うだけです。" +"Sphinx のバージョンを上げ、papa.io の intersphinx を削除した。 (:pr:`625`)" -#: ../source/overview.rst:145 -msgid "A summary of Python's packaging capabilities for tools and libraries." -msgstr "ツールやライブラリ向けの Python のパッケージング機能の概要。" +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr ":file:`find_namespace_packages` に言及した。 (:pr:`622`)" -#: ../source/overview.rst:145 -msgid "" -"Python's recommended built-in library and tool packaging technologies. " -"Excerpted from `The Packaging Gradient (2017) `_." +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "一貫性確保のためにディレクトリ配置の例を更新した。 (:pr:`611`)" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "Bandersnatch の GitHub へのリンクを更新した。 (:pr:`623`)" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "2019年6月" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "いくつかの誤記を訂正した。 (:pr:`620`)" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "2019年5月" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" msgstr "" -"Python が推奨するライブラリやツールをパッケージングする技術。`パッケージング" -"の変遷 (2017) `_ から抜粋。" +":file:`python_requires` の使い方をパッケージングチュートリアルに追記した。 (:" +"pr:`613`)" -#: ../source/overview.rst:152 -msgid "Packaging Python applications" -msgstr "Python アプリケーションをパッケージングする" +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "MANIFEST.in について説明するページを追加した。 (:pr:`609`)" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "2019年4月" -#: ../source/overview.rst:154 +#: ../source/news.rst:35 msgid "" -"So far we've only discussed Python's native distribution tools. Based on our " -"introduction, you would be correct to infer these built-in approaches only " -"target environments which have Python, and an audience who knows how to " -"install Python packages." +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" msgstr "" -"ここまで、 Python に元々組み込まれている配布ツールについてだけ議論してきまし" -"た。この導入部分に基づいて、これらのビルトインされたアプローチが Python のあ" -"る環境だけを対象にしたもので、聞き手は Python パッケージのインストール方法を" -"知っているものと推測するのは正しいでしょう。" +":file:`shiv` への言及を嗅ぎとなるプロジェクト群の節に追加した。 (:pr:`608`)" -#: ../source/overview.rst:159 -msgid "" -"With the variety of operating systems, configurations, and people out there, " -"this assumption is only safe when targeting a developer audience." -msgstr "" -"多様なオペレーティングシステム・設定・そこに居る人々を想定すると、聞き手が開" -"発者である場合にだけこの仮定が正当であると言えます。" +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "virtualenv に関する強調を減少させた。 (:pr:`606`)" -#: ../source/overview.rst:163 -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 `." -msgstr "" -"Python に元々組み込まれているパッケージング機能は、ほとんどの場合には、開発者" -"間で再利用可能なソースコードや呼び出されるライブラリを配布するために作られて" -"います。 :doc:`setuptools のエントリポイント ` のような技術を用いることで、 Python の packaging ライブラリの上" -"に構築されている **ツール類** や開発者向けの基本的なアプリケーションに便乗す" -"ることができます。" +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "2019年3月" -#: ../source/overview.rst:169 -msgid "" -"Libraries are building blocks, not complete applications. For distributing " -"applications, there's a whole new world of technologies out there." +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" msgstr "" -"ライブラリは部品であって完成したアプリケーションではありません。アプリケー" -"ションを配布するには、全く新しい技術の世界が広がっています。" +"「パッケージのバージョンを１箇所で管理する」の項を Python 3 側に移した。 (:" +"pr:`605`)" -#: ../source/overview.rst:173 -msgid "" -"The next few sections organize these application packaging options according " -"to their dependencies on the target environment, so you can choose the right " -"one for your project." -msgstr "" -"ここからのいくつかの節では、ターゲットとなる環境への依存関係に従ってこのよう" -"なアプリケーションをパッケージングする選択肢を整理し、あなたのプロジェクトに" -"最適なものを選択できるようにしましょう。" +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "RTD の詳細について貢献方法のところでカバーした。 (:pr:`600`)" -#: ../source/overview.rst:178 -msgid "Depending on a framework" -msgstr "フレームワークに依存する" +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "2019年2月" -#: ../source/overview.rst:180 +#: ../source/news.rst:45 msgid "" -"Some types of Python applications, like web site backends and other network " -"services, are common enough that they have frameworks to enable their " -"development and packaging. Other types of applications, like dynamic web " -"frontends and mobile clients, are complex enough to target that a framework " -"becomes more than a convenience." +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" msgstr "" -"ウェブサイトのバックエンドやその他のネットワークサービスのような、いくつかの" -"種類の Python アプリケーションでは、その開発とパッケージングを可能にするフ" -"レームワークが存在することは極めてありふれたことです。動的ウェブのフロントエ" -"ンドやモバイルクライアントのような他の種類のアプリケーションはとても複雑で、" -"フレームワークが単に便利という以上の存在になっています。" +"チュートリアルの内容と実際のパッケージングプロセスの間の差異について詳しく述" +"べた。 (:pr:`602`)" -#: ../source/overview.rst:186 -msgid "" -"In all these cases, it makes sense to work backwards, from the framework's " -"packaging and deployment story. Some frameworks include a deployment system " -"which wraps the technologies outlined in the rest of the guide. In these " -"cases, you'll want to defer to your framework's packaging guide for the " -"easiest and most reliable production experience." +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" msgstr "" -"これら全てのケースで、フレームワークのパッケージングと配置の物語から振り返っ" -"てみるのが妥当でしょう。いくつかのフレームワークは、このガイドの残りの部分で" -"概要を描き出す技術を内包する配置システムを含んでいます。このような場合には、" -"最も簡単で最も信頼できる製品レベルの経験を積むまで、あなたのフレームワークの" -"パッケージングガイドを延期しておきたくなるでしょう。" +"Python の CLI アプリケーションをインストールするための指示書きを追加した。 (:" +"pr:`594`)" -#: ../source/overview.rst:192 -msgid "" -"If you ever wonder how these platforms and frameworks work under the hood, " -"you can always read the sections beyond." +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "2019年1月" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" msgstr "" -"このようなプラットフォームやフレームワークが内部でどのように動作しているのか" -"と不思議に思うのであれば、いつでもその先の節を読めば良いでしょう。" +"パッケージングチュートリアルに :file:`--no-deps` を追加した。 (:pr:`593`)" -#: ../source/overview.rst:196 -msgid "Service platforms" -msgstr "サービスプラットフォーム" +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "Sphinx と Nox について更新した。 (:pr:`591`)" -#: ../source/overview.rst:198 -msgid "" -"If you're developing for a \"`Platform-as-a-Service `_\" or \"PaaS\", you are going to want to " -"follow their respective packaging guides. These types of platforms take care " -"of packaging and deployment, as long as you follow their patterns. Most " -"software does not fit one of these templates, hence the existence of all the " -"other options below." -msgstr "" -"\"`Platform-as-a-Service `_\" もしくは \"PaaS\" 上で開発を行っているのであれば、" -"当該 PaaS のパッケージガイドに従う方が良いと思うようになることでしょう。この" -"ようなタイプのプラットフォームは、彼らの流儀に従っている限りはパッケージング" -"やデプロイメントの面倒を見てくれます。後述する他のすべてのオプションが存在す" -"るので、ほとんどのソフトウェアはこれらのテンプレートのひとつにはうまく合致し" -"ません。" +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "Python 3 の項に Twine への言及を追加した。 (:pr:`581`)" -#: ../source/overview.rst:205 -msgid "" -"If you're developing software that will be deployed to machines you own, " -"users' personal computers, or any other arrangement, read on." -msgstr "" -"自分の機材やユーザのパーソナルコンピュータやその他の機材に配置することを想定" -"するソフトウェアを開発しているのであれば、このまま読み進めてください。" +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "2018年12月" -#: ../source/overview.rst:209 -msgid "Web browsers and mobile applications" -msgstr "ウェブブラウザとモバイルアプリケーション" +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "事務所にプログラマが居ません！" -#: ../source/overview.rst:211 -msgid "" -"Python's steady advances are leading it into new spaces. These days you can " -"write a mobile app or web application frontend in Python. While the language " -"may be familiar, the packaging and deployment practices are brand new." -msgstr "" -"Python は着実に前進して新しい世界に突入しています。最近では、モバイルアプリや" -"ウェブアプリケーションのフロントエンドを Python で書くことができるようになっ" -"ています。言語自体には慣れていても、パッケージングや配置の実務は全く新しいも" -"のになっています。" +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "2018年11月" -#: ../source/overview.rst:216 -msgid "" -"If you're planning on releasing to these new frontiers, you'll want to check " -"out the following frameworks, and refer to their packaging guides:" -msgstr "" -"このような新しい未開拓分野でリリースを計画しているのであれば、以下のフレーム" -"ワークに興味が湧いて、それぞれのパッケージングガイドを参照したくなるかもしれ" -"ません。" +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "PyPI 移行ガイドへのランディングページリンクを削除した。 (:pr:`575`)" -#: ../source/overview.rst:220 -msgid "`Kivy `_" -msgstr "" +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "bumpversion を bump2version に変更した。 (:pr:`572`)" -#: ../source/overview.rst:221 -msgid "`Beeware `_" -msgstr "`Beeware `_" +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "パッケージバージョンの一元管理の例を追加した。 (:pr:`573`)" -#: ../source/overview.rst:222 -msgid "`Brython `_" -msgstr "`Brython `_" +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "ドキュメント作成のためのガイドを追加した。 (:pr:`568`)" -#: ../source/overview.rst:223 -msgid "`Flexx `_" -msgstr "" +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "2018年10月" -#: ../source/overview.rst:225 -msgid "" -"If you are *not* interested in using a framework or platform, or just wonder " -"about some of the technologies and techniques utilized by the frameworks " -"above, continue reading below." -msgstr "" -"フレームワークやプラットフォームに興味がなければ、あるいは、上記のフレーム" -"ワークが利用している技術や手練手管について不思議に思うのであれば、このまま読" -"み進めてください。" +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "Nox パッケージの名称を更新した。 (:pr:`566`)" -#: ../source/overview.rst:230 -msgid "Depending on a pre-installed Python" -msgstr "インストール済みの Python に依存する" +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "ガイドの中で Sphinx 拡張について言及した。 (:pr:`562`)" -#: ../source/overview.rst:232 -msgid "" -"Pick an arbitrary computer, and depending on the context, there's a very " -"good chance Python is already installed. Included by default in most Linux " -"and Mac operating systems for many years now, you can reasonably depend on " -"Python preexisting in your data centers or on the personal machines of " -"developers and data scientists." -msgstr "" -"任意のコンピュータを選んだ時に、もちろんその環境にもよりますが、 Python が既" -"にインストールされている確率は相当に高いでしょう。 Linux や Mac オペレーティ" -"ングシステムではもう多年にわたってデフォルトでインストールされているので、" -"データセンタの機材や、開発者やデータ科学者の個人用の機材には Python が入って" -"いるものと思っても構わないでしょう。" +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "2018年9月" -#: ../source/overview.rst:238 -msgid "Technologies which support this model:" -msgstr "このモデルを支える技術:" +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "RST マークアップの検査に関する節を追加した。 (:pr:`554`)" -#: ../source/overview.rst:240 -msgid ":gh:`PEX ` (Python EXecutable)" -msgstr ":gh:`PEX ` (Python EXecutable)" +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "ユーザによるインストールのページを更新した。 (:pr:`558`)" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "Google BigQuery の url を更新した。 (:pr:`556`)" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "tar コマンドについて動作するコマンドに置換した。 (:pr:`552`)" -#: ../source/overview.rst:241 +#: ../source/news.rst:76 msgid "" -":doc:`zipapp ` (does not help manage dependencies, " -"requires Python 3.5+)" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" msgstr "" -":doc:`zipapp ` (依存関係を管理する助けにはならない。" -"Python 3.5+ が必要。)" +"pip インストールで SomeProject==1.4 と書くところをダブルクォーテーションマー" +"クに変更した。 (:pr:`550`)" -#: ../source/overview.rst:242 -msgid ":gh:`shiv ` (requires Python 3)" -msgstr ":gh:`shiv ` (Python 3 が必要)" +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "2018年8月" -#: ../source/overview.rst:244 -msgid "" -"Of all the approaches here, depending on a pre-installed Python relies the " -"most on the target environment. Of course, this also makes for the smallest " -"package, as small as single-digit megabytes, or even kilobytes." -msgstr "" -"ここでのすべてのアプローチでは、ほとんどのインストール先となる環境にインス" -"トール済みの Python があるものと当てにしています。もちろん、これは、一桁メガ" -"バイト規模やさらにはキロバイト規模の最小のパッケージを作ることになります。" +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "パスワードを平文で保存することを推奨していたのを削除した。 (:pr:`546`)" -#: ../source/overview.rst:249 +#: ../source/news.rst:81 msgid "" -"In general, decreasing the dependency on the target system increases the " -"size of our package, so the solutions here are roughly arranged by " -"increasing size of output." -msgstr "" -"一般に、インストール先の環境に対する依存を減少させるとパッケージ側のサイズは" -"大きくなるので、ここで述べる解決策は、おおまかに出力となるパッケージのサイズ" -"の増える順番に整理しています。" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "他のものに加えて、概要をタスク別の見出しに移した。 (:pr:`540`)" -#: ../source/overview.rst:256 -msgid "Depending on a separate software distribution ecosystem" -msgstr "個別のソフトウェア配布エコシステムに依存する" +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "virtualenv がサポートする Python のバージョンを更新した。 (:pr:`538`)" -#: ../source/overview.rst:258 -msgid "" -"For a long time many operating systems, including Mac and Windows, lacked " -"built-in package management. Only recently did these OSes gain so-called " -"\"app stores\", but even those focus on consumer applications and offer " -"little for developers." -msgstr "" -"長い間、Mac や Windows を含むさまざまなオペレーティングシステムは、組み込みの" -"パッケージ管理システムを欠いてきました。ごく最近になって、これらの OS にも所" -"謂「アプリストア (app stores)」が追加されましたが、しかし、まだ消費者向けのア" -"プリケーションを扱っているだけであり、開発者の役に立つものは少ないのが現状で" -"す。" +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "新しい概要のページのあらまし/ラフな下書きを追加した。 (:pr:`519`)" -#: ../source/overview.rst:263 -msgid "" -"Developers long sought remedies, and in this struggle, emerged with their " -"own package management solutions, such as `Homebrew `_. " -"The most relevant alternative for Python developers is a package ecosystem " -"called `Anaconda `_. Anaconda is built around Python and is " -"increasingly common in academic, analytical, and other data-oriented " -"environments, even making its way `into server-oriented environments " -"`_." -msgstr "" -"長い間、開発者が解決方法を探し求めてきており、この格闘の中から `Homebrew " -"`_ のような独自のパッケージ管理手法が勃興した。 Python 開発" -"者にとっての最も適切な代替方法は、 `Anaconda `_ と呼ばれるパッケージエコシステムです。 " -"Anaconda は Python を中核として作成されており、学術や分析やデータ主導の環境で" -"より一層一般的になってきていて、`サーバ中心の環境に `_ さえ入り込んでいます。" +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "2018年7月" -#: ../source/overview.rst:273 -msgid "Instructions on building and publishing for the Anaconda ecosystem:" -msgstr "Anaconda エコシステム向けにビルドし公開するための指示書き:" +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "バイナリ拡張に関する説明文書を改善した。 (:pr:`531`)" -#: ../source/overview.rst:275 -msgid "" -"`Building libraries and applications with conda `_" -msgstr "" -"`conda でライブラリやアプリケーションをビルドする `_" +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "scikit-build を主要プロジェクトに追加した。 (:pr:`530`)" -#: ../source/overview.rst:276 -msgid "" -"`Transitioning a native Python package to Anaconda `_" -msgstr "" -"`Python 由来のパッケージを Anaconda へ移行する `_" +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "2018年6月" -#: ../source/overview.rst:278 -msgid "" -"A similar model involves installing an alternative Python distribution, but " -"does not support arbitrary operating system-level packages:" -msgstr "" -"よく似たモデルが Python 配布物の代替物をインストールする際にも適用されます" -"が、オペレーティングシステムレベルのパッケージはサポートしていません。" +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "pypa.io に関する相互運用性 PEP のカテゴリ分けを修正した。 (:pr:`527`)" -#: ../source/overview.rst:282 -msgid "" -"`ActiveState ActivePython `_" -msgstr "" -"`ActiveState ActivePython `_" +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "descriptions をマークダウンで書く場合の説明を更新した。 (:pr:`522`)" -#: ../source/overview.rst:283 -msgid "`WinPython `_" -msgstr "`WinPython `_" +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "2018年5月" -#: ../source/overview.rst:288 -msgid "Bringing your own Python executable" -msgstr "自分の Python 実行形式を持ち込む" +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "Provides-Diet と Obsolete-Diet の課題を注記した。 (:pr:`513`)" -#: ../source/overview.rst:290 +#: ../source/news.rst:101 msgid "" -"Computing as we know it is defined by the ability to execute programs. Every " -"operating system natively supports one or more formats of programs they can " -"natively execute." +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" msgstr "" -"我々が知るところのコンピューティングは、プログラムを実行する能力として定義さ" -"れます。それぞれのオペレーティングシステムは、そのまま実行することが可能なひ" -"とつかもっと多くのプログラムフォーマットを元々サポートしています。" +"Pipenv で異なるバージョンの Python を使う場合の警告が古くなっていたので削除し" +"た。 (:pr:`501`)" -#: ../source/overview.rst:294 -msgid "" -"There are many techniques and technologies which turn your Python program " -"into one of these formats, most of which involve embedding the Python " -"interpreter and any other dependencies into a single executable file." -msgstr "" -"そのようなフォーマットにあなたの Python プログラムを変換する数多くの手練手管" -"や技術が存在していて、そのほとんどでは Python インタープリタやその他の依存先" -"を単一の実行形式のファイルに組み込むことになるでしょう。" +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "パッケージングのチュートリアルを簡素にした。 (:pr:`498`)" -#: ../source/overview.rst:299 -msgid "" -"This approach, called *freezing*, offers wide compatibility and seamless " -"user experience, though often requires multiple technologies, and a good " -"amount of effort." -msgstr "" -"*フリージング* と呼ばれるこの方法論は、しばしば複数の技術と共にかなりの努力を" -"要求しますが、幅広い互換性と継ぎ目のないユーザ経験を提供します。" +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "明確性のため、 Windows ユーザ向けの指示を更新した。 (:pr:`493`)" -#: ../source/overview.rst:303 -msgid "A selection of Python freezers:" -msgstr "Python フリーザの選択肢:" +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "完全性のためにライセンスの節の記述を更新した。 (:pr:`492`)" -#: ../source/overview.rst:305 -msgid "" -"`pyInstaller `_ - Cross-" -"platform" -msgstr "" -"`pyInstaller `_ - クロスプラッ" -"トフォーム" +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "「貢献するには」の節に仕様のスタイルの記述を追加した。 (:pr:`489`)" -#: ../source/overview.rst:306 -msgid "" -"`cx_Freeze `_ - Cross-platform" -msgstr "" -"`cx_Freeze `_ - クロスプラット" -"フォーム" +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "「貢献するには」ガイドにドキュメントのタイプを追記した。 (:pr:`485`)" -#: ../source/overview.rst:307 -msgid "" -"`constructor `_ - For command-line " -"installers" +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "2018年4月" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "README ガイドを追加した。 (:pr:`461`)" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "PyPI の供用開始についてやり方と状態を更新した。 (:pr:`475`)" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "Warehouse についての指示を追加した。 (:pr:`471`)" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" msgstr "" -"`constructor `_ - コマンドラインインス" -"トーラ向け" +"(パッケージを?) 公開するチュートリアルから GPG の参照情報を削除した。 (:pr:" +"`466`)" -#: ../source/overview.rst:308 -msgid "`py2exe `_ - Windows only" -msgstr "`py2exe `_ - Windows 限定" +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "「Python 3.4-3.6 では何がどれに入ってる？」を追加した。 (:pr:`468`)" -#: ../source/overview.rst:309 -msgid "`py2app `_ - Mac only" -msgstr "`py2app `_ - Mac 限定" +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" +"あるバージョンの Python を徐々に使わなくするガイドを追加した。 (:pr:`459`)" -#: ../source/overview.rst:310 -msgid "`osnap `_ - Windows and Mac" -msgstr "`osnap `_ - Windows と Mac" +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" +"変種の GFM をデフォルトの Description-Content-Type とした。 (:pr:`462`)" -#: ../source/overview.rst:311 -msgid "`pynsist `_ - Windows only" -msgstr "`pynsist `_ - Windows 限定" +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "2018年3月" -#: ../source/overview.rst:313 +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "「科学計算分野のパッケージ群」を更新した。 (:pr:`455`)" + +#: ../source/news.rst:123 msgid "" -"Most of the above imply single-user deployments. For multi-component server " -"applications, see :gh:`Chef Omnibus `." +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" msgstr "" -"上記のものはほとんどが単独のユーザでの配置です。複数部分から構成されるサーバ" -"アプリケーション向けには :gh:`Chef Omnibus ` を見てください。" +"PEP 556 に従う :file:`long_description_content_type` を追加した。 (:pr:`457`)" -#: ../source/overview.rst:319 -msgid "Bringing your own userspace" -msgstr "自分自身のユーザスペースを持ち込む" +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" +"pypi.org における long description 分類子について明確化した。 (:pr:`456`)" -#: ../source/overview.rst:321 +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "コアとなるメタデータ仕様が PEP 556 に従うように更新した。 (:pr:`412`)" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "2018年2月" + +#: ../source/news.rst:130 msgid "" -"An increasing number of operating systems -- including Linux, Mac OS, and " -"Windows -- can be set up to run applications packaged as lightweight images, " -"using a relatively modern arrangement often referred to as `operating-system-" -"level virtualization `_, or *containerization*." +"Added python3-venv and python3-pip to Debian installation instructions. (:pr:" +"`445`)" msgstr "" -"オペレーティングシステム -- Linux や Mac OS や Windows を含む -- で、しばし" -"ば `オペレーティングシステムレベルの仮想化 `_ もしくは *コンテナ化* として参照され" -"る相対的に新しい手法を用いた、軽量のイメージとしてパッケージされたアプリケー" -"ションを走らせるように設定することができるものが数を増しています。" +"Debian でのインストール指示に python3-venv と python3-pip を追記した。 (:pr:" +"`445`)" -#: ../source/overview.rst:328 +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "PyPI 移行情報を更新した。 (:pr:`439`)" + +#: ../source/news.rst:132 msgid "" -"These techniques are mostly Python agnostic, because they package whole OS " -"filesystems, not just Python or Python packages." +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" msgstr "" -"このような手法は Python 単体もしくは Python パッケージではなく OS のファイル" -"システム全体をパッケージ化するので、ほとんどの場合には Python を直接にサポー" -"トしているわけではありません。" +"複数のバージョンの pipenv を取り扱う際の注意事項を追記した。 (:pr:`430`)" -#: ../source/overview.rst:331 -msgid "" -"Adoption is most extensive among Linux servers, where the technology " -"originated and where the technologies below work best:" +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" msgstr "" -"(訳注、このような技術の) 取り入れが最も広範囲に渡るのは、この技術の発祥の地で" -"あり下に述べる技術が最もうまく動作する Linux サーバです:" +"コアとなるメタデータの項に複数の電子メールアドレスの例を追加した。 (:pr:" +"`429`)" -#: ../source/overview.rst:334 -msgid "`AppImage `_" -msgstr "`AppImage `_" +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "test.pypi.org/legacy に \"legacy\" の説明を加えた。 (:pr:`426`)" -#: ../source/overview.rst:335 -msgid "`Docker `_" -msgstr "`Docker `_" +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "2018年1月" -#: ../source/overview.rst:336 -msgid "`Flatpak `_" -msgstr "`Flatpak `_" +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "PyPI にある分類子のリストへのリンクを追加した。 (:pr:`425`)" -#: ../source/overview.rst:337 -msgid "`Snapcraft `_" -msgstr "`Snapcraft `_" +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "README.rst についての説明を更新した。 (:pr:`419`)" -#: ../source/overview.rst:340 -msgid "Bringing your own kernel" -msgstr "自分自身のカーネルを持ち込む" +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "2017年12月" -#: ../source/overview.rst:342 +#: ../source/news.rst:145 msgid "" -"Most operating systems support some form of classical virtualization, " -"running applications packaged as images containing a full operating system " -"of their own. Running these virtual machines, or VMs, is a mature approach, " -"widespread in data center environments." +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" msgstr "" -"ほとんどのオペレーティングシステムでは、何らかの形であるオペレーティングシス" -"テム全体を内包するイメージの形にパッケージされたアプリケーションを動作させる" -"ことができるような、古典的な仮想化がサポートされています。このような仮想マシ" -"ンもしくは VM を動作させることは枯れた方法論で、データセンタ環境に広く普及し" -"ています。" +"ガイドやチュートリアルで :file:`~` を :file:`$HOME` に置き換えた。 (:pr:" +"`418`)" -#: ../source/overview.rst:347 -msgid "" -"These techniques are mostly reserved for larger scale deployments in data " -"centers, though certain complex applications can benefit from this " -"packaging. The technologies are Python agnostic, and include:" +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" msgstr "" -"複雑なアプリケーションの中にはこのパッケージング方法から利益を得るものもあり" -"ますが、このような手法はたいていの場合はデータセンタにおけるかなり大規模な配" -"置のために使用します。技術としては Python を直接サポートしているわけではな" -"く、次のものを含みます:" - -#: ../source/overview.rst:351 -msgid "`Vagrant `_" -msgstr "`Vagrant `_" +"環境マーカとともにどのフィールドを使うことができるのかについて注記した。 (:" +"pr:`416`)" -#: ../source/overview.rst:352 -msgid "" -"`VHD `_, `AMI `_, and :doc:`other formats " -"`" -msgstr "" -"`VHD `_ や `AMI `_ や :doc:`他のフォーマット " -"`" +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "Requires-Python の節を更新した。 (:pr:`414`)" -#: ../source/overview.rst:353 -msgid "" -"`OpenStack `_ - A cloud " -"management system in Python, with extensive VM support" -msgstr "" -"`OpenStack `_ - 大規模な VM サ" -"ポート機能がついていて Python で書かれたクラウド管理システム" +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "ニュースのページを追加した。 (:pr:`404`)" -#: ../source/overview.rst:356 -msgid "Bringing your own hardware" -msgstr "自分自身のハードウェアを持ち込む" +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "2017年11月" -#: ../source/overview.rst:358 +#: ../source/news.rst:153 msgid "" -"The most all-encompassing way to ship your software would be to ship it " -"already-installed on some hardware. This way, your software's user would " -"require only electricity." +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" msgstr "" -"最もすべてを包含した方法は、あなたのソフトウェアを何らかのハードウェア上にイ" -"ンストールして出荷することです。この方法では、あなたのソフトウェアのユーザは" -"電力供給しか要求されません。" +"Pipenv を基盤とした依存関係の管理に関するチュートリアルを新たに追加した。 (:" +"pr:`402`)" -#: ../source/overview.rst:362 +#: ../source/news.rst:154 msgid "" -"Whereas the virtual machines described above are primarily reserved for the " -"tech-savvy, you can find hardware appliances being used by everyone from the " -"most advanced data centers to the youngest children." +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" msgstr "" -"上で述べた仮想マシンがもっぱら技術に明るい人向けであるのに対し、ハードウェア" -"によるアプライアンス機器は最先端のデータセンタから最も若い子供たちまでの誰に" -"でも使えます。" +"*パッケージバージョンの一元管理* のチュートリアルが pip の現在の戦略を反映す" +"るように更新した。 (:pr:`400`)" -#: ../source/overview.rst:366 +#: ../source/news.rst:156 msgid "" -"Embed your code on an :gh:`Adafruit `, `MicroPython " -"`_, or more-powerful hardware running Python, then " -"ship it to the datacenter or your users' homes. They plug and play, and you " -"can call it a day." +"Added documentation about the ``py_modules`` argument to ``setup``. (:pr:" +"`398`)" msgstr "" -":gh:`Adafruit ` や `MicroPython `_ 、あるいは、もっとパワーのあるハードウェアで Python が動作するものに" -"あなたのプログラムを組み込んで、データセンタやあなたのユーザの家に出荷しま" -"しょう。彼らはプラグアンドプレイで使うし、あなたはその日の仕事を終わりにでき" -"るでしょう。" - -#: ../source/overview.rst:375 -msgid "A summary of technologies used to package Python applications." -msgstr "Python アプリケーションをパッケージするのに使われる技術の概要。" +"``setup`` に対する ``py_modules`` 引数について説明を追加した。 (:pr:`398`)" -#: ../source/overview.rst:375 -msgid "" -"The simplified gamut of technologies used to package Python applications." -msgstr "" -"Python アプリケーションをパッケージするのに使われる技術の単純化された全体像。" +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr ":file:`manifest.in` 節での用語を簡素化した。 (:pr:`395`)" -#: ../source/overview.rst:378 -msgid "What about..." -msgstr "これは何..." +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "2017年10月" -#: ../source/overview.rst:380 +#: ../source/news.rst:162 msgid "" -"The sections above can only summarize so much, and you might be wondering " -"about some of the more conspicuous gaps." -msgstr "" -"上記の節ではかなり要約して書いているので、飛躍している点が目につくかもしれま" -"せん。" - -#: ../source/overview.rst:384 -msgid "Operating system packages" -msgstr "オペレーティングシステムレベルのパッケージ" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr ":file:`entry_points.txt` ファイルの仕様を追記した。 (:pr:`398`)" -#: ../source/overview.rst:386 +#: ../source/news.rst:163 msgid "" -"As mentioned in :ref:`depending-on-a-separate-ecosystem` above, some " -"operating systems have package managers of their own. If you're very sure of " -"the operating system you're targeting, you can depend directly on a format " -"like `deb `_ (for Debian, " -"Ubuntu, etc.) or `RPM `_ " -"(for Red Hat, Fedora, etc.), and use that built-in package manager to take " -"care of installation, and even deployment. You can even use `FPM `_ to generate " -"both deb and RPMs from the same source." +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" msgstr "" -"上記の :ref:`depending-on-a-separate-ecosystem` で言及したように、オペレー" -"ティングシステムの中には独自のパッケージ管理機構を備えているものがあります。" -"あなたがターゲットにするオペレーティングシステムが非常にはっきりわかっている" -"なら、 `deb `_ (Debian や " -"Ubuntu その他向け。) か、 `RPM `_ (Red Hat や Fedora その他向け。) のようなフォーマット" -"を直接利用して、インストールや配置さえもその面倒を見るのに組み込みのパッケー" -"ジ管理機構を活用することができます。 `FPM `_ を使えば、同じソースコードから deb " -"と RPM の両方を生成することさえ可能です。" +"``pip`` や ``virtualenv`` を用いてパッケージを管理するためのガイドを新設し" +"た。 (:pr:`385`)" -#: ../source/overview.rst:397 -msgid "" -"In most deployment pipelines, the OS package manager is just one piece of " -"the puzzle." -msgstr "" -"ほとんどの配置パイプラインでは、 OS パッケージ管理機構は全体から見ればほんの" -"一部です。" +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "仕様のページを複数ページに分割した。 (:pr:`386`)" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "2017年9月" -#: ../source/overview.rst:403 +#: ../source/news.rst:169 msgid "" -":doc:`Virtualenvs ` have been an indispensable " -"tool for multiple generations of Python developer, but are slowly fading " -"from view, as they are being wrapped by higher-level tools. With packaging " -"in particular, virtualenvs are used as a primitive in :doc:`the dh-" -"virtualenv tool ` and `osnap `_, both of which wrap virtualenvs in a self-contained way." +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. (:pr:" +"`379`)" msgstr "" -":doc:`Virtualenvs ` は、複数世代の Python 向け" -"に開発をする者にとっては以前から避けられないツールであり続けてきたが、高レベ" -"ルのツール群がラップするようになったので徐々に見えなくなりつつあります。特に" -"パッケージングの観点では、共に virtualenvs を内包する形でラップしている :doc:" -"`the dh-virtualenv tool ` や `osnap `_ では virtualenvs はプリミティブとして使われています。" +":file:`README.rst` を検証するために ``readme_renderer`` を使用することを推奨" +"するようにした。 (:pr:`379`)" -#: ../source/overview.rst:412 +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "``--user-base`` オプションの使用を推奨するようにした。 (:pr:`374`)" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "2017年8月" + +#: ../source/news.rst:176 msgid "" -"For production deployments, do not rely on running ``python -m pip install`` " -"from the Internet into a virtualenv, as one might do in a development " -"environment. The overview above is full of much better solutions." +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" msgstr "" -"開発環境ではありがちですが、商用環境への配置ではインターネットから " -"virtualenv への ``python -m pip install`` を走らせることに信用をおいてはなり" -"ません。上に述べた概要には、より良い解決策がたくさんあります。" +"``Pipenv`` を用いてパッケージをインストールする方法について新たに試験的な" +"チュートリアルを追加した。 (:pr:`369`)" -#: ../source/overview.rst:417 -msgid "Security" -msgstr "セキュリティ" +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "``TestPyPI`` を使う方法について新たにガイドを追加した。 (:pr:`366`)" -#: ../source/overview.rst:419 +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr ":file:`pypi.org` を用語として追加した。 (:pr:`365`)" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "2017年7月" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "``flit`` を鍵となるプロジェクト群のリストに追加した。 (:pr:`358`)" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "``enscons `` を鍵となるプロジェクト群のリストに追加した。 (:pr:`357`)" + +#: ../source/news.rst:185 msgid "" -"The further down the gradient you come, the harder it gets to update " -"components of your package. Everything is more tightly bound together." +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" msgstr "" -"あなたのパッケージの部品を更新することは、ここまで積み上げてきたものよりさら" -"に困難なものになるでしょう。あらゆるものがより緊密に互いに固着しているので" -"す。" +"本ガイドの ``readme`` にローカル環境でこのガイドをビルドする方法を追加して更" +"新した。 (:pr:`356`)" -#: ../source/overview.rst:422 +#: ../source/news.rst:186 msgid "" -"For example, if a kernel security issue emerges, and you're deploying " -"containers, the host system's kernel can be updated without requiring a new " -"build on behalf of the application. If you deploy VM images, you'll need a " -"new build. Whether or not this dynamic makes one option more secure is still " -"a bit of an old debate, going back to the still-unsettled matter of `static " -"versus dynamic linking `_." +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" msgstr "" -"例えば、仮にあなたがコンテナ型の仮想環境を配置していて、カーネルのセキュリ" -"ティ問題が発生したとすれば、アプリケーションに新たなビルドを要求することなく" -"ホスト側のカーネルが更新されるかもしれません。もしあなたが VM イメージを配置" -"しているなら、それを再ビルドする必要があるかもしれません。このような動的な挙" -"動をよりセキュアにするひとつのオプションは、以前から少々議論の的になっている" -"がまだ決着のついていない `静的リンク対動的リンク `_ ということになります。" - -#: ../source/overview.rst:431 -msgid "Wrap up" -msgstr "まとめ" +"ホームページにpypi.org に関する注記を加えることで、新しい ``TestPyPI`` の " +"URL がより目立つようにした。 (:pr:`354`)" -#: ../source/overview.rst:433 +#: ../source/news.rst:187 msgid "" -"Packaging in Python has a bit of a reputation for being a bumpy ride. This " -"impression is mostly a byproduct of Python's versatility. Once you " -"understand the natural boundaries between each packaging solution, you begin " -"to realize that the varied landscape is a small price Python programmers pay " -"for using one of the most balanced, flexible languages available." +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "明示的な登録を行う API の削除について注記を追加した。 (:pr:`347`)" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "2017年6月" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" msgstr "" -"Python におけるパッケージングは、凸凹道を車で行くようなもので苦労が多いという" -"評判も少しあります。このような感想は、ほとんどの場合は Python が多用途に使え" -"ることの裏返しです。それぞれのパッケージング方法の間にある自然な境界線を理解" -"しさえすれば、さまざまに異なる風景が、もっともバランスが取れていて自由度の高" -"い言語を使うということのために Python プログラマが支払う小さな代償であること" -"に気づくことでしょう。" +":file:`PyPI.org` へのアップロード方法の変更について説明を追加した。 (:pr:" +"`339`)" -#: ../source/specifications/binary-distribution-format.rst:7 -msgid "Binary distribution format" -msgstr "バイナリ配布物のフォーマット" +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "``python_requires`` について説明を追加した。 (:pr:`338`)" -#: ../source/specifications/binary-distribution-format.rst:9 +#: ../source/news.rst:194 msgid "" -"This page specifies the binary distribution format for Python packages, also " -"called the wheel format." +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. (:" +"pr:`335`)" msgstr "" -"このページでは、Python パッケージのバイナリ配布物フォーマット、これは wheel " -"フォーマットとも呼ばれているものですが、これについて仕様を記述します。" +"*推奨されるツール* のチュートリアル内で PyPI の移転に関する注記を追加した。 " +"(:pr:`335`)" -#: ../source/specifications/binary-distribution-format.rst:12 +#: ../source/news.rst:195 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 " -"installed according to PEP 376 with a particular installation scheme. " -"Although a specialized installer is recommended, a wheel file may be " -"installed by simply unpacking into site-packages with the standard 'unzip' " -"tool while preserving enough information to spread its contents out onto " -"their final paths at any later time." +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" msgstr "" -"wheel は、特別にフォーマットされたファイル名と ``.whl`` 拡張子を持った ZIP " -"フォーマットのアーカイブです。 PEP 376 にほぼ従ってインストールされる単一の配" -"布物を含んでいます。特別なインストーラを使うことが推奨されていますが、 wheel " -"ファイルは、いつでも後でその最終的なパス名の場所に内容物を展開するに足りる情" -"報を保存しつつ、サイトパッケージを置くべき場所に標準の 'unxip' ツールで単純に" -"アンパックすればインストールできます。" +":file:`manifest.in` が wheel には影響を与えないことを注記した。 (:pr:`332`)" -#: ../source/specifications/binary-distribution-format.rst:22 -msgid "Details" -msgstr "詳細" +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "配布ガイドにライセンスの節を追加した。 (:pr:`331`)" -#: ../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/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "``name`` 引数に関する節を拡充した。 (:pr:`329`)" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "Wheel installation notionally consists of two phases:" -msgstr "Wheel によるインストールは、概念上、ふたつの段階から構成されています:" +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "ランディングページを調整した。 (:pr:`327`, :pr:`326`, :pr:`324`)" -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "Unpack." -msgstr "アンパックする。" +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "Sphinx 1.6.2 にバージョンを上げた。 (:pr:`323`)" -#: ../source/specifications/binary-distribution-format.rst:31 -msgid "Parse ``distribution-1.0.dist-info/WHEEL``." -msgstr "``distribution-1.0.dist-info/WHEEL`` をパースします。" +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "PyPA のテーマに切り替えた。 (:pr:`305`)" -#: ../source/specifications/binary-distribution-format.rst:32 +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "説明文書を新しい構造に再編成した。 (:pr:`318`)" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "2017年5月" + +#: ../source/news.rst:206 msgid "" -"Check that installer is compatible with Wheel-Version. Warn if minor " -"version is greater, abort if major version is greater." +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "``Description-Content-Type`` 欄について説明を追加した。 (:pr:`258`)" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "貢献者向けのガイドとスタイルガイドを追加した。 (:pr:`307`)" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" msgstr "" -"インストーラが Wheel のバージョンと互換であることを確認します。マイナーバー" -"ジョンが大きければ警告し、メジャーバージョンが大きければ処理を中断します。" +"プロジェクト単位の索引における ``pip`` と ``easy_install`` の差異について説明" +"した。 (:pr:`233`)" -#: ../source/specifications/binary-distribution-format.rst:34 +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "2017年4月" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "プルリクエストの試験のための travis 設定を追記した。 (:pr:`300`)" + +#: ../source/news.rst:214 msgid "" -"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +"Mentioned the requirement of the ``wheel`` package for creating wheels (:pr:" +"`299`)" msgstr "" -"もし、 Root-Is-Purelib == 'true' であれば、アーカイブを purelib (site-" -"packages) へアンパックします。" +"wheel ファイルを生成するための ``wheel`` パッケージへの要求条件に言及するよう" +"にした。 (:pr:`299`)" -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "Else unpack archive into platlib (site-packages)." +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" msgstr "" -"そうでなければ、アーカイブを platlib (site-packages) へアンパックします。" +"*パッケージを配布する* チュートリアルにおいて ``twine register`` への参照を削" +"除した。 (:pr:`271`)" -#: ../source/specifications/binary-distribution-format.rst:38 -msgid "Spread." -msgstr "広げる。" +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "プラグインの検索に関する話題を追加した。 (:pr:`294`, :pr:`296`)" -#: ../source/specifications/binary-distribution-format.rst:40 +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "名前空間パッケージの話題を追加した。 (:pr:`290`)" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" +"``pip`` を ``/usr/local`` にインストールする方法を目立つように説明する文書を" +"追加した。 (:pr:`230`)" + +#: ../source/news.rst:219 msgid "" -"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " -"data) ``distribution-1.0.data/``." +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" msgstr "" -"アンパックされたアーカイブは、 ``distribution-1.0.dist-info/`` と (データ部分" -"があれば) ``distribution-1.0.data/`` を含んでいます。" +"開発モードの説明文書を更新して、ローカルパッケージの記入順に意味があることに" +"言及するようにした。 (:pr:`208`)" -#: ../source/specifications/binary-distribution-format.rst:42 +#: ../source/news.rst:220 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 " -"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" -"headers|scripts|data)``. The initially supported paths are taken from " -"``distutils.command.install``." +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" msgstr "" -"``distribution-1.0.data/`` の下の全てのサブツリーを、その目的地となるディレク" -"トリパスに移動します。 ``distribution-1.0.data/(purelib|platlib|headers|" -"scripts|data)`` のような ``distribution-1.0.data/`` の下のそれぞれのサブディ" -"レクトリは、目的地となるディレクトリパスの辞書になっています。初期状態でサ" -"ポートされているパスは ``distutils.command.install`` から取り込まれます。" +"ホストしているプロジェクトのところで readthedocs の引っ越しに合わせてリンク" +"を ``.org`` から ``.io`` に変更した。 (:pr:`239`)" -#: ../source/specifications/binary-distribution-format.rst:48 +#: ../source/news.rst:221 msgid "" -"If applicable, update scripts starting with ``#!python`` to point to the " -"correct interpreter." +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" msgstr "" -"もし該当するならば、 ``#!python`` から始まるスクリプト群が適切なインタープリ" -"タを指し示すように更新します。" +"順序が意味を持つので、アップロードコマンドの :file:`setup.py` の引数の順序を" +"入れ替えた。 (:pr:`260`)" -#: ../source/specifications/binary-distribution-format.rst:50 -msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" msgstr "" -"``distribution-1.0.dist-info/RECORD`` をインストール先のディレクトリパスに更" -"新します。" +"サポートされていないソースからヘルパーアプリケーションを用いてインストールす" +"る方法について説明した。 (:pr:`289`)" -#: ../source/specifications/binary-distribution-format.rst:52 -msgid "Remove empty ``distribution-1.0.data`` directory." -msgstr "空の ``distribution-1.0.data`` ディレクトリを削除します。" +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "2017年3月" -#: ../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.)" +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" msgstr "" -"インストールされた .py のファイルを全て .pyc にコンパイルします。 (アンインス" -"トーラは、 RECORD で言及されていなくても .pyc ファイルを削除できるほどに賢く" -"あるべきです。)" +"*プラットフォームWheels* の項で ``manylinux1`` をカバーした。 (:pr:`283`)" -#: ../source/specifications/binary-distribution-format.rst:57 -msgid "Recommended installer features" -msgstr "推奨されるインストーラの機能" +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "2017年2月" -#: ../source/specifications/binary-distribution-format.rst:67 -msgid "Rewrite ``#!python``." -msgstr "``#!python`` を書き換えます。" +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr ":pep:`518` を追加した。 (:pr:`281`)" -#: ../source/specifications/binary-distribution-format.rst:60 +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "Python におけるパッケージングに関する概要" + +#: ../source/overview.rst:7 msgid "" -"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" -"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" -"python'``, rewrite to point to the correct interpreter. Unix installers may " -"need to add the +x bit to these files if the archive was created on Windows." +"As a general-purpose programming language, Python is designed to be used in " +"many ways. You can build web sites or industrial robots or a game for your " +"friends to play, and much more, all using the same core technology." msgstr "" -"wheel では、スクリプトは ``{distribution}-{version}.data/scripts/`` にパッ" -"ケージされます。 ``scripts/`` ディレクトリにあるファイルの先頭行が正確に " -"``b'#!python'`` で始まっている場合には、正確なインタープリタを指し示すように" -"書き換えられます。アーカイブが Windows で作成されていれば、 Unix でのインス" -"トーラがこのようなファイルに +x ビットを追加設定する必要があるでしょう。" +"汎用プログラミング言語として Python は数多くの用途に使えるように設計されてい" +"ます。ウェブサイト構築にも産業用ロボットにもあなたが友達と一緒に遊ぶゲームに" +"ももっと他の用途にも、同じコア技術が使えるのです。" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/overview.rst:12 msgid "" -"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " -"script instead of a console script." +"Python's flexibility is why the first step in every Python project must be " +"to think about the project's audience and the corresponding environment " +"where the project will run. It might seem strange to think about packaging " +"before writing code, but this process does wonders for avoiding future " +"headaches." msgstr "" -"``b'#!pythonw'`` と書く慣習も許容されています。 ``b'#!pythonw'`` というのはコ" -"ンソール版ではなくて GUI 版のスクリプトであることを示します。" - -#: ../source/specifications/binary-distribution-format.rst:72 -msgid "Generate script wrappers." -msgstr "スクリプトラッパを生成します。" +"Python は自由度が高いので、プロジェクトの利用者について、また、それに対応して" +"プロジェクトが動作するであろう環境について、すべての Python プロジェクトにお" +"いて最初に考えなければなりません。コードを書く前にパッケージングについて考え" +"ておくというのは奇妙に見えるかもしれませんが、この作業こそが将来の頭痛の種を" +"摘み取るという驚くべきことを起こすのです。" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/overview.rst:18 msgid "" -"In wheel, scripts packaged on Unix systems will certainly not have " -"accompanying .exe wrappers. Windows installers may want to add them during " -"install." +"This overview provides a general-purpose decision tree for reasoning about " +"Python's plethora of packaging options. Read on to choose the best " +"technology for your next project." msgstr "" -"wheel では、 Unix システム上でパッケージされたスクリプトには .exe ラッパーが" -"随伴していないことが普通でしょう。 Windows インストーラは、インストールする際" -"にそれらを追加したくなるかもしれません。" - -#: ../source/specifications/binary-distribution-format.rst:75 -msgid "Recommended archiver features" -msgstr "推奨されるアーカイバの機能" +"この概要文書は、 Python の過剰とも言える多数のパッケージング手段からどれを選" +"択するかについての汎用の決定木を提供します。読み進めて、あなたの次のプロジェ" +"クトにとっての最適解を選んでください。" -#: ../source/specifications/binary-distribution-format.rst:82 -msgid "Place ``.dist-info`` at the end of the archive." -msgstr "アーカイブの末尾に ``.dist-info`` を置くこと。" +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "デプロイメントについて検討する" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/overview.rst:25 msgid "" -"Archivers are encouraged to place the ``.dist-info`` files physically at the " -"end of the archive. This enables some potentially interesting ZIP tricks " -"including the ability to amend the metadata without rewriting the entire " -"archive." +"Packages exist to be installed (or *deployed*), so before you package " +"anything, you'll want to have some answers to the deployment questions below:" msgstr "" -"アーカイバには、 ``.dist-info`` ファイルをアーカイブの物理的な末尾に置くこと" -"が推奨されています。こうすることで、アーカイブ全体を書き換えなくてもメタデー" -"タを修正することができる点を含む、 ZIP のいくつかの潜在的に興味深いトリックを" -"使うことができるようになります。" - -#: ../source/specifications/binary-distribution-format.rst:85 -msgid "File Format" -msgstr "ファイルフォーマット" - -#: ../source/specifications/binary-distribution-format.rst:88 -#: ../source/specifications/binary-distribution-format.rst:90 -msgid "File name convention" -msgstr "ファイル名の慣習" +"パッケージはインストールされる(あるいは *配置* される)ために存在しているの" +"で、なにかをパッケージ化する前に次のような配置のための質問にいくらかの答えを" +"持っておきたいと思うでしょう:" -#: ../source/specifications/binary-distribution-format.rst:90 -#: ../source/specifications/binary-distribution-format.rst:92 +#: ../source/overview.rst:29 msgid "" -"The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" -"{abi tag}-{platform tag}.whl``." +"Who are your software's users? Will your software be installed by other " +"developers doing software development, operations people in a datacenter, or " +"a less software-savvy group?" msgstr "" -"wheel のファイル名は(訳注、慣習として) ``{配布物}-{バージョン}(-{ビルドタ" -"グ})?-{python タグ}-{abi タグ}-{プラットフォームタグ}.whl <{distribution}-" -"{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl>`` です。" - -#: ../source/specifications/binary-distribution-format.rst:94 -#: ../source/specifications/binary-distribution-format.rst:96 -msgid "distribution" -msgstr "配布物" +"あなたのソフトウェアのユーザはどんな人たちでしょうか？ソフトウェアを開発する" +"他の開発者たちがインストールするのでしょうか、データセンタでオペレーションを" +"する人々でしょうか、それとも、ソフトウェアを知り尽くしているとは言えないよう" +"な人たちでしょうか？" -#: ../source/specifications/binary-distribution-format.rst:94 -#: ../source/specifications/binary-distribution-format.rst:96 -msgid "Distribution name, e.g. 'django', 'pyramid'." -msgstr "配布物の名前、例えば 'django' や 'pyramid' 。" +#: ../source/overview.rst:32 +msgid "" +"Is your software intended to run on servers, desktops, mobile clients " +"(phones, tablets, etc.), or embedded in dedicated devices?" +msgstr "" +"あなたのソフトウェアは、サーバ上で走らせることを想定していますか、それとも、" +"デスクトップ、モバイル端末 (携帯電話やタブレット端末等) 、あるいは、専用端末" +"に組み込む形で？" -#: ../source/specifications/binary-distribution-format.rst:97 -#: ../source/specifications/binary-distribution-format.rst:99 -msgid "version" +#: ../source/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" msgstr "" +"あなたのソフトウェアは、単独でインストールされるものですか、それとも、巨大な" +"デプロイメントバッチの一部として？" -#: ../source/specifications/binary-distribution-format.rst:97 -#: ../source/specifications/binary-distribution-format.rst:99 -msgid "Distribution version, e.g. 1.0." -msgstr "配布物のバージョン、例えば 1.0 。" +#: ../source/overview.rst:36 +msgid "" +"Packaging is all about target environment and deployment experience. There " +"are many answers to the questions above and each combination of " +"circumstances has its own solutions. With this information, the following " +"overview will guide you to the packaging technologies best suited to your " +"project." +msgstr "" +"パッケージングとは、インストール先となる環境と配置(デプロイ)経験に関わるすべ" +"てのことです。上に述べた質問には多くの回答があり、それぞれの事情の組み合わせ" +"ごとに解決策が存在します。この情報とともに、以下の概要説明の中で、あなたのプ" +"ロジェクトに最適なパッケージング技術についてご案内します。" -#: ../source/specifications/binary-distribution-format.rst:122 -#: ../source/specifications/binary-distribution-format.rst:124 -msgid "build tag" -msgstr "ビルドタグ" +#: ../source/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "Python のライブラリやツールをパッケージングする" -#: ../source/specifications/binary-distribution-format.rst:100 -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/overview.rst:45 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, " -"and other tags). Sort as an empty tuple if unspecified, else sort as a two-" -"item tuple with the first item being the initial digits as an ``int``, and " -"the second item being the remainder of the tag as a ``str``." +"You may have heard about PyPI, ``setup.py``, and ``wheel`` files. These are " +"just a few of the tools Python's ecosystem provides for distributing Python " +"code to developers, which you can read about in :doc:`guides/distributing-" +"packages-using-setuptools`." msgstr "" -"省略可能なビルドナンバー。数字で始まらなければなりません。ふたつの wheel ファ" -"イルのファイル名がこの部分を除いて (すなわち名称やバージョンやその他のタグ" -"が) 同一であった場合のタイブレーカ (訳注、いずれかに決めるための方法) として" -"働きます。指定されていれば先頭の数字を ``int`` として解釈して第１要素とし残り" -"を ``str`` として解釈して第２要素とするような要素数が２個のタプルとして解釈さ" -"れ、指定されていない場合には空欄のタプルとして解釈されます。" +"PyPI や ``setup.py`` 、 ``wheel`` ファイルについて聞いたことがあるかもしれま" +"せん。これらは Python のソースコードを開発者に配布するための Python エコシス" +"テムのほんの一部で、これらについては :doc:`guides/distributing-packages-" +"using-setuptools` に説明があります。" -#: ../source/specifications/binary-distribution-format.rst:107 -#: ../source/specifications/binary-distribution-format.rst:109 +#: ../source/overview.rst:50 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." +"The following approaches to packaging are meant for libraries and tools used " +"by technical audience in a development setting. If you're looking for ways " +"to package Python for a non-technical audience and/or a production setting, " +"skip ahead to :ref:`packaging-applications`." msgstr "" -"ビルド番号に係るよくあるユースケースは、CPython のリリース前のバージョンを" -"使って manylinux で配布物をビルドしている場合のように、ビルド環境に変化があっ" -"たためにバイナリ配布物を再ビルドする時です。" +"パッケージングに関する以下のアプローチは、開発環境における技術に明るい聞き手" +"が用いるライブラリやツールを念頭に置いています。技術にあまり明るくない聞き手" +"向けに Python をパッケージする方法や、製品使用環境での方法を探している場合" +"は、 :ref:`アプリケーションをパッケージングする` まで飛ばしてください。" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "Python モジュール" -#: ../source/specifications/binary-distribution-format.rst:114 -#: ../source/specifications/binary-distribution-format.rst:116 +#: ../source/overview.rst:58 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." +"A Python file, provided it only relies on the standard library, can be " +"redistributed and reused. You will also need to ensure it's written for the " +"right version of Python, and only relies on the standard library." msgstr "" -"ビルド番号は、配布物のバージョンの一部ではなく、従って外部からの、特に " -"Python エコシステムのツール類や標準類の外側からの参照は困難です。配布物が外部" -"からの参照を必要とするようなケースとしては、セキュリティ上の脆弱性を解決しよ" -"うとする場合がよくあるケースです。" +"標準ライブラリだけに依存している Python のファイルは、再配布して再利用するこ" +"とができます。他には正しいバージョンの Python 用に書かれていることと、標準ラ" +"イブラリだけに依存していることを確実にしておけば良いでしょう。" -#: ../source/specifications/binary-distribution-format.rst:119 -#: ../source/specifications/binary-distribution-format.rst:121 +#: ../source/overview.rst:63 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." +"This is great for sharing simple scripts and snippets between people who " +"both have compatible Python versions (such as via email, StackOverflow, or " +"GitHub gists). There are even some entire Python libraries that offer this " +"as an option, such as :doc:`bottle.py` and :doc:`boltons " +"`." msgstr "" -"この制約のゆえに、外部から参照される必要がある新たな配布物は、新しい配布物を" -"ビルドする際にビルド番号を使う **べきではありません** 。そのような場合には、" -"代わりに **新しい配布物バージョン** が作成されるべきです。" - -#: ../source/specifications/binary-distribution-format.rst:125 -#: ../source/specifications/binary-distribution-format.rst:127 -msgid "language implementation and version tag" -msgstr "言語の実装とバージョンタグ" - -#: ../source/specifications/binary-distribution-format.rst:125 -#: ../source/specifications/binary-distribution-format.rst:127 -msgid "E.g. 'py27', 'py2', 'py3'." -msgstr "例えば、 'py27' ・ 'py2' ・ 'py3' 。" - -#: ../source/specifications/binary-distribution-format.rst:128 -#: ../source/specifications/platform-compatibility-tags.rst:20 -#: ../source/specifications/binary-distribution-format.rst:130 -msgid "abi tag" -msgstr "abi タグ" - -#: ../source/specifications/binary-distribution-format.rst:128 -#: ../source/specifications/binary-distribution-format.rst:130 -msgid "E.g. 'cp33m', 'abi3', 'none'." -msgstr "例えば、 'cp33m' ・ 'abi3' ・ 'none' 。" +"この方法は、単純なスクリプトやスニペットを互換性のあるバージョンの Python を" +"持っている人たちどうしで (電子メールや StackOverflow や GitHub gists などで) " +"共有するには優れた方法です。例えば :doc:`bottle.py ` や :" +"doc:`boltons ` のように、 Python ライブラリ全体をこのや" +"り方で共有することをオプションの一つとして提供しているものさえあります。" -#: ../source/specifications/binary-distribution-format.rst:131 -#: ../source/specifications/platform-compatibility-tags.rst:23 -#: ../source/specifications/binary-distribution-format.rst:133 -msgid "platform tag" -msgstr "プラットフォームタグ" +#: ../source/overview.rst:70 +msgid "" +"However, this pattern won't scale for projects that consist of multiple " +"files, need additional libraries, or need a specific version of Python, " +"hence the options below." +msgstr "" +"しかしながら、複数のファイルで構成されるプロジェクトや追加のライブラリを必要" +"とするもの、また、特定バージョンの Python を必要とするものには適用できず、そ" +"の場合には下のようなやり方が選択肢になります。" -#: ../source/specifications/binary-distribution-format.rst:131 -#: ../source/specifications/binary-distribution-format.rst:133 -msgid "E.g. 'linux_x86_64', 'any'." -msgstr "例えば、 'linux_x86_64' ・ 'any' 。" +#: ../source/overview.rst:75 +msgid "Python source distributions" +msgstr "Python ソースコード配布物" -#: ../source/specifications/binary-distribution-format.rst:133 -#: ../source/specifications/binary-distribution-format.rst:135 +#: ../source/overview.rst:77 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 " -"Python 2.7 implementation), with no ABI (pure Python), on any CPU " -"architecture." +"If your code consists of multiple Python files, it's usually organized into " +"a directory structure. Any directory containing Python files can comprise " +"an :term:`Import Package`." msgstr "" -"例えば、 ``distribution-1.0.1-py27-none-any.whl`` とは、 'distribution' と呼" -"ばれるパッケージの最初のビルドであって、 Python 2.7 (任意の Python 2.7 実装) " -"で動作し、 ABI を持たず (即ち純 Python) 、任意の CPU アーキテクチャで動作する" -"ということです。" +"あなたのソースコードが複数の Python ファイルでできているなら、ディレクトリ構" +"造の中に整理してあるのが普通です。 Python ファイルを置いてあるディレクトリな" +"らどれでも、 :term:`パッケージインポート ` ができるはずです。" -#: ../source/specifications/binary-distribution-format.rst:138 -#: ../source/specifications/binary-distribution-format.rst:140 +#: ../source/overview.rst:81 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." +"Because packages consist of multiple files, they are harder to distribute. " +"Most protocols support transferring only one file at a time (when was the " +"last time you clicked a link and it downloaded multiple files?). It's easier " +"to get incomplete transfers, and harder to guarantee code integrity at the " +"destination." msgstr "" -"ファイル名の拡張子を除いて最後の３個の構成要素は、\"互換性タグ\" と呼ばれま" -"す。互換性タグは、インタープリタに対するそのパッケージの基本的な要求事項を表" -"現しており、 PEP 425 に詳しく書かれています。" - -#: ../source/specifications/binary-distribution-format.rst:143 -#: ../source/specifications/binary-distribution-format.rst:145 -msgid "Escaping and Unicode" -msgstr "エスケープとユニコード" +"パッケージは複数のファイルで構成されるので、その配布がやや難しくなります。ほ" +"とんどのプロトコルではたった一個のファイルしか一度に送ることができません (リ" +"ンクをクリックしたら複数のファイルをダウンロードしたことあります？)。不完全な" +"転送になってしまうことは容易く、送り先でソースコードの完全性を保証することは" +"困難です。" -#: ../source/specifications/binary-distribution-format.rst:145 -#: ../source/specifications/binary-distribution-format.rst:147 +#: ../source/overview.rst:87 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:" +"So long as your code contains nothing but pure Python code, and you know " +"your deployment environment supports your version of Python, then you can " +"use Python's native packaging tools to create a *source* :term:`Distribution " +"Package`, or *sdist* for short." msgstr "" -"ファイル名の構成要素がダッシュ (``-`` つまり HYPHEN-MINUS) で分離されているの" -"で、この文字は構成要素の中に出現してはなりません。これは次のように取り扱われ" -"ます:" +"あなたのソースコードが純粋な Python コード以外は何も含んでいない間は、そし" +"て、配置先の環境であなたが想定しているバージョンの Python が動作することを" +"知っていれば、 Python 由来のパッケージングツールを使って *ソースコード* :" +"term:`配布パッケージ ` もしくは 短縮系で*sdist* を使え" +"ば良いでしょう。" -#: ../source/specifications/binary-distribution-format.rst:148 -#: ../source/specifications/binary-distribution-format.rst:150 +#: ../source/overview.rst:92 msgid "" -"In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " -"and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " -"characters should be replaced with corresponding lowercase ones. This is " -"equivalent to regular :ref:`name normalization ` " -"followed by replacing ``-`` with ``_``. Tools consuming wheels must be " -"prepared to accept ``.`` (FULL STOP) and uppercase letters, however, as " -"these were allowed by an earlier version of this specification." +"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 go to the :ref:`source-distribution-" +"format` specification to learn more." msgstr "" -"配布物の名前の部分では、 ``-_.`` (HYPHEN-MINUS ・ LOW LINE ・ FULL STOP) の文" -"字は、すべて ``_`` (LOW LINE) で置き換えられるべきで、かつ、大文字はすべて対" -"応する小文字に置き換えられるべきです。これは、通常の :ref:`名前の正規化 " -"` の後に ``-`` を ``_`` で置き換えるのと同じです。 wheel " -"ファイルを入力とするツールは、 ``.`` (FULL STOP) や大文字を受け入れる準備がで" -"きていなければなりませんが、しかし、それはこの仕様の初期のバージョンで許され" -"ていたからです。" +"Python の *sdists* は圧縮済みのアーカイブ (``.tar.gz`` ファイル) で、ひとつか" +"それ以上のパッケージないしモジュールを内包しています。もしあなたのソースコー" +"ドが純粋に Python だけで書かれていて、他の Python パッケージに依存しているだ" +"けなら、 :ref:`ソースコード配布物フォーマット ` " +"仕様を見ればもっと詳しく知ることができます。" -#: ../source/specifications/binary-distribution-format.rst:155 -#: ../source/specifications/binary-distribution-format.rst:157 +#: ../source/overview.rst:97 msgid "" -"Version numbers should be normalised according to the :ref:`Version " -"specifier specification `. Normalised version numbers " -"cannot contain ``-``." +"If you rely on any non-Python code, or non-Python packages (such as `libxml2 " +"`_ in the case of `lxml `_, or BLAS libraries in the case of `numpy `_), you will need to use the format detailed in the next " +"section, which also has many advantages for pure-Python libraries." msgstr "" -"バージョン番号は、 `バージョン指定子仕様 ` に従って正規化" -"されなければなりません。正規化済みのバージョン番号は ``-`` を含んでいてはなり" -"ません。" +"もし非 Python のソースコード、あるいは、非 Python のパッケージ (`lxml " +"`_ における`libxml2 `_ や、`numpy `_ における " +"BLAS ライブラリなど) に依存しているなら、純 Python で書かれたライブラリにとっ" +"ても多くの利点がある、次の節で詳細に説明されるフォーマットを使う必要があるで" +"しょう。" -#: ../source/specifications/binary-distribution-format.rst:157 -#: ../source/specifications/binary-distribution-format.rst:159 +#: ../source/overview.rst:104 msgid "" -"The remaining components may not contain ``-`` characters, so no escaping is " -"necessary." +"Python and PyPI support multiple distributions providing different " +"implementations of the same package. For instance the unmaintained-but-" +"seminal `PIL distribution `_ provides the PIL " +"package, and so does `Pillow `_, an " +"actively-maintained fork of PIL!" msgstr "" -"残りの構成要素は、 ``-`` 文字を含んでいてはいけないので、エスケープ処理を行う" -"必要がありません。" +"Python と PyPI は、同一のパッケージの異なる実装を提供する複数の配布物をサポー" +"トしています。例えば、もはや保守されてはいないが先駆的で重要な `PIL 配布物 " +"`_ が PIL パッケージを提供しているし、 PIL か" +"らフォークして今も活発に保守されている `Pillow `_ も同様です！" -#: ../source/specifications/binary-distribution-format.rst:160 -#: ../source/specifications/binary-distribution-format.rst:162 +#: ../source/overview.rst:111 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." +"This Python packaging superpower makes it possible for Pillow to be a drop-" +"in replacement for PIL, just by changing your project's ``install_requires`` " +"or ``requirements.txt``." msgstr "" -"wheel ファイルを生成するツールはファイル名部分の構成要素が ``-`` を含んでいな" -"いことを検証しなければなりませんが、これは、もし含んでいれば結果として生成さ" -"れたファイルが正しく処理されないかもしれないからです。" +"この Python パッケージングの素晴らしいパワーで、あなたのプロジェクトの " +"``install_requires`` か ``requirements.txt`` を変更するだけで Pillow が PIL " +"に対して単純に入れ替えるだけで済む代替物になっているのです。" -#: ../source/specifications/binary-distribution-format.rst:163 -#: ../source/specifications/binary-distribution-format.rst:165 +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "Python バイナリ配布物" + +#: ../source/overview.rst:118 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." +"So much of Python's practical power comes from its ability to integrate with " +"the software ecosystem, in particular libraries written in C, C++, Fortran, " +"Rust, and other languages." msgstr "" -"アーカイブのファイル名は Unicode です。いくつかのツールでは非 ASCII 文字の" -"ファイル名をサポートするように更新されるまでに幾らかの時間がかかるかもしれま" -"せんが、しかし、この仕様ではサポートされているのです。" +"Python の実際的な力の多くは、ソフトウェアのエコシステム、とりわけ C ・ C++ " +"・ Fortran ・ Rust ・その他の言語で書かれたライブラリと統合できる能力からもた" +"らされます。" -#: ../source/specifications/binary-distribution-format.rst:167 -#: ../source/specifications/binary-distribution-format.rst:169 +#: ../source/overview.rst:122 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``." +"Not all developers have the right tools or experiences to build these " +"components written in these compiled languages, so Python created the :term:" +"`Wheel`, a package format designed to ship libraries with compiled " +"artifacts. In fact, Python's package installer, ``pip``, always prefers " +"wheels because installation is always faster, so even pure-Python packages " +"work better with wheels." msgstr "" -"アーカイブの *中にある* ファイルのファイル名は、 UTF-8 でエンコードされていま" -"す。 ZIP クライアントのいくつかは共通して UTF-8 のファイル名を正常に表示しま" -"せんが、このエンコーディングは ZIP の仕様でも Python の ``zipfile`` の仕様で" -"も、共にサポートされています。" - -#: ../source/specifications/binary-distribution-format.rst:173 -#: ../source/specifications/binary-distribution-format.rst:175 -msgid "File contents" -msgstr "ファイルの内容" +"このようなコンパイルを必要とする言語で書かれた部品をビルドするのに適切なツー" +"ルや経験をすべての開発者が持っているわけではないので、ライブラリをコンパイル" +"済みの状態で出荷するように設計された :term:`Wheel` を Python は作りました。実" +"際に、 Python のパッケージインストーラである ``pip`` は、インストールが素早く" +"できるので常に wheel ファイルを選好するし、純 Python のパッケージでさえも " +"wheel ファイルの方がうまく動作します。" -#: ../source/specifications/binary-distribution-format.rst:175 -#: ../source/specifications/binary-distribution-format.rst:177 -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:" +#: ../source/overview.rst:129 +msgid "" +"Binary distributions are best when they come with source distributions to " +"match. Even if you don't upload wheels of your code for every operating " +"system, by uploading the sdist, you're enabling users of other platforms to " +"still build it for themselves. Default to publishing both sdist and wheel " +"archives together, *unless* you're creating artifacts for a very specific " +"use case where you know the recipient only needs one or the other." msgstr "" -"{distribution} の部分を例えば ``beaglevote`` のようなパッケージ名で置き換" -"え、 {version} の部分を例えば `1.0.0`` のようなバージョン番号で置き換えた " -"wheel ファイルの内容は次のもので構成されています:" +"バイナリ配布物は、対応するソースコード配布物と一緒に配布されるのが最良です。 " +"あらゆるオペレーティングシステム用のソースコードの wheel ファイルをアップロー" +"ドしていないとしても、sdist をアップロードすることで他のプラットフォームの" +"ユーザたちがビルドすることができるかもしれません。あなたが極めて特殊なユース" +"ケース向けにプログラムを作成していて、受け取る人たちがいずれか一方しか必要と" +"しないことを熟知しているので *ない限り* 、 sdist と wheel の両方を一緒に公開" +"することをデフォルトにしてください。" -#: ../source/specifications/binary-distribution-format.rst:179 -#: ../source/specifications/binary-distribution-format.rst:181 +#: ../source/overview.rst:137 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``." +"Python and PyPI make it easy to upload both wheels and sdists together. Just " +"follow the :doc:`tutorials/packaging-projects` tutorial." msgstr "" -"アーカイブのルートディレクトリに当たる ``/`` は、``WHEEL`` で指定されている通" -"り ``purelib`` または ``platlib`` にインストールされるファイルをすべて含んで" -"います。通常は、 ``purelib`` や ``platlib`` はいずれも ``site-packages`` で" -"す。" +"Python と PyPI を使えば、wheel ファイルと sdist ファイルを一緒にアップロード" +"するのが簡単になります。 :doc:`tutoeials/packaging-projects` のチュートリアル" +"に従うだけです。" -#: ../source/specifications/binary-distribution-format.rst:182 -#: ../source/specifications/binary-distribution-format.rst:184 -msgid "``{distribution}-{version}.dist-info/`` contains metadata." -msgstr "``{distribution}-{version}.dist-info/`` はメタデータを含んでいます。" +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "ツールやライブラリ向けの Python のパッケージング機能の概要。" -#: ../source/specifications/binary-distribution-format.rst:183 -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/overview.rst:145 msgid "" -"``{distribution}-{version}.data/`` contains one subdirectory for each non-" -"empty install scheme key not already covered, where the subdirectory name is " -"an index into a dictionary of install paths (e.g. ``data``, ``scripts``, " -"``headers``, ``purelib``, ``platlib``)." +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." msgstr "" -"``{distribution}-{version}.data/`` は、すでにカバーされているものは別として、" -"サブディレクトリ名がインストールパスの辞書への (例えば、 ``data``, " -"``scripts``, ``headers``, ``purelib``, ``platlib`` のような) 指示子になってい" -"るような、空ではないそれぞれのインストールスキームに対応したディレクトリを含" -"みます。" +"Python が推奨するライブラリやツールをパッケージングする技術。`パッケージング" +"の変遷 (2017) `_ から抜粋。" -#: ../source/specifications/binary-distribution-format.rst:187 -#: ../source/specifications/binary-distribution-format.rst:189 +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "Python アプリケーションをパッケージングする" + +#: ../source/overview.rst:154 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." +"So far we've only discussed Python's native distribution tools. Based on our " +"introduction, you would be correct to infer these built-in approaches only " +"target environments which have Python, and an audience who knows how to " +"install Python packages." msgstr "" -"Python スクリプトは ``scripts`` ディレクトリに置かなければならず、また、イン" -"ストール時のスクリプトラッパの生成や ``#!python`` 書き換えといった利点を活用" -"するために、正確に ``b'#!python'`` で始まっていなければなりません。" +"ここまで、 Python に元々組み込まれている配布ツールについてだけ議論してきまし" +"た。この導入部分に基づいて、これらのビルトインされたアプローチが Python のあ" +"る環境だけを対象にしたもので、聞き手は Python パッケージのインストール方法を" +"知っているものと推測するのは正しいでしょう。" -#: ../source/specifications/binary-distribution-format.rst:191 -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/overview.rst:159 msgid "" -"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " -"greater format metadata." +"With the variety of operating systems, configurations, and people out there, " +"this assumption is only safe when targeting a developer audience." msgstr "" -"``{distribution}-{version}.dist-info/METADATA`` は、バージョン 1.1 またはそれ" -"以上のフォーマットのメタデータです。" +"多様なオペレーティングシステム・設定・そこに居る人々を想定すると、聞き手が開" +"発者である場合にだけこの仮定が正当であると言えます。" -#: ../source/specifications/binary-distribution-format.rst:193 -#: ../source/specifications/binary-distribution-format.rst:195 +#: ../source/overview.rst:163 msgid "" -"``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " -"itself in the same basic key: value format::" +"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 `." msgstr "" -"``{distribution}-{version}.dist-info/WHEEL`` は、同様のキー:バリュー形式で表" -"現されたアーカイブそのものに関するメタデータです::" - -#: ../source/specifications/binary-distribution-format.rst:203 -#: ../source/specifications/binary-distribution-format.rst:205 -msgid "``Wheel-Version`` is the version number of the Wheel specification." -msgstr "``Wheel-Version`` は、Wheel の仕様のバージョン番号です。" +"Python に元々組み込まれているパッケージング機能は、ほとんどの場合には、開発者" +"間で再利用可能なソースコードや呼び出されるライブラリを配布するために作られて" +"います。 :doc:`setuptools のエントリポイント ` のような技術を用いることで、 Python の packaging ライブラリの上" +"に構築されている **ツール類** や開発者向けの基本的なアプリケーションに便乗す" +"ることができます。" -#: ../source/specifications/binary-distribution-format.rst:204 -#: ../source/specifications/binary-distribution-format.rst:206 +#: ../source/overview.rst:169 msgid "" -"``Generator`` is the name and optionally the version of the software that " -"produced the archive." +"Libraries are building blocks, not complete applications. For distributing " +"applications, there's a whole new world of technologies out there." msgstr "" -"``Generator`` は、そのアーカイブを作成したソフトウェアの名前で、バージョン番" -"号を付加しても構いません。" +"ライブラリは部品であって完成したアプリケーションではありません。アプリケー" +"ションを配布するには、全く新しい技術の世界が広がっています。" -#: ../source/specifications/binary-distribution-format.rst:206 -#: ../source/specifications/binary-distribution-format.rst:208 +#: ../source/overview.rst:173 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." +"The next few sections organize these application packaging options according " +"to their dependencies on the target environment, so you can choose the right " +"one for your project." msgstr "" -"``Root-Is-Purelib`` は、アーカイブの最上位のディレクトリが pure lib へインス" -"トールされるべきものであれば true で、そうでなければ platlib へインストールさ" -"れます。" +"ここからのいくつかの節では、ターゲットとなる環境への依存関係に従ってこのよう" +"なアプリケーションをパッケージングする選択肢を整理し、あなたのプロジェクトに" +"最適なものを選択できるようにしましょう。" -#: ../source/specifications/binary-distribution-format.rst:209 -#: ../source/specifications/binary-distribution-format.rst:211 +#: ../source/overview.rst:178 +msgid "Depending on a framework" +msgstr "フレームワークに依存する" + +#: ../source/overview.rst:180 msgid "" -"``Tag`` is the wheel's expanded compatibility tags; in the example the " -"filename would contain ``py2.py3-none-any``." +"Some types of Python applications, like web site backends and other network " +"services, are common enough that they have frameworks to enable their " +"development and packaging. Other types of applications, like dynamic web " +"frontends and mobile clients, are complex enough to target that a framework " +"becomes more than a convenience." msgstr "" -"``Tag`` は、 wheel の拡張互換性タグで、例の中ではファイル名の ``py2.py3-none-" -"any`` の部分です。" +"ウェブサイトのバックエンドやその他のネットワークサービスのような、いくつかの" +"種類の Python アプリケーションでは、その開発とパッケージングを可能にするフ" +"レームワークが存在することは極めてありふれたことです。動的ウェブのフロントエ" +"ンドやモバイルクライアントのような他の種類のアプリケーションはとても複雑で、" +"フレームワークが単に便利という以上の存在になっています。" -#: ../source/specifications/binary-distribution-format.rst:211 -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/overview.rst:186 msgid "" -"``Build`` is the build number and is omitted if there is no build number." +"In all these cases, it makes sense to work backwards, from the framework's " +"packaging and deployment story. Some frameworks include a deployment system " +"which wraps the technologies outlined in the rest of the guide. In these " +"cases, you'll want to defer to your framework's packaging guide for the " +"easiest and most reliable production experience." msgstr "" -"``Build`` は、ビルドナンバーで、もしビルドナンバーがなければ省略されます。" +"これら全てのケースで、フレームワークのパッケージングと配置の物語から振り返っ" +"てみるのが妥当でしょう。いくつかのフレームワークは、このガイドの残りの部分で" +"概要を描き出す技術を内包する配置システムを含んでいます。このような場合には、" +"最も簡単で最も信頼できる製品レベルの経験を積むまで、あなたのフレームワークの" +"パッケージングガイドを延期しておきたくなるでしょう。" -#: ../source/specifications/binary-distribution-format.rst:212 -#: ../source/specifications/binary-distribution-format.rst:214 +#: ../source/overview.rst:192 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." +"If you ever wonder how these platforms and frameworks work under the hood, " +"you can always read the sections beyond." msgstr "" -"wheel インストーラは、もし自身がサポートしているものより Wheel-Version が大き" -"ければ警告するべきですし、 Wheel-Version のメジャーバージョンがサポートしてい" -"るものより大きい場合にはフェイルするべきです。" +"このようなプラットフォームやフレームワークが内部でどのように動作しているのか" +"と不思議に思うのであれば、いつでもその先の節を読めば良いでしょう。" -#: ../source/specifications/binary-distribution-format.rst:215 -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "サービスプラットフォーム" + +#: ../source/overview.rst:198 msgid "" -"Wheel, being an installation format that is intended to work across multiple " -"versions of Python, does not generally include .pyc files." +"If you're developing for a \"`Platform-as-a-Service `_\" or \"PaaS\", you are going to want to " +"follow their respective packaging guides. These types of platforms take care " +"of packaging and deployment, as long as you follow their patterns. Most " +"software does not fit one of these templates, hence the existence of all the " +"other options below." msgstr "" -"Wheel は複数のバージョンの Python を跨いでも動作するように意図されたインス" -"トール用のフォーマットですが、通常は .pyc ファイルを含みません。" - -#: ../source/specifications/binary-distribution-format.rst:217 -#: ../source/specifications/binary-distribution-format.rst:219 -msgid "Wheel does not contain setup.py or setup.cfg." -msgstr "Wheel は、 setup.py ないし setup.cfg を含みません。" +"\"`Platform-as-a-Service `_\" もしくは \"PaaS\" 上で開発を行っているのであれば、" +"当該 PaaS のパッケージガイドに従う方が良いと思うようになることでしょう。この" +"ようなタイプのプラットフォームは、彼らの流儀に従っている限りはパッケージング" +"やデプロイメントの面倒を見てくれます。後述する他のすべてのオプションが存在す" +"るので、ほとんどのソフトウェアはこれらのテンプレートのひとつにはうまく合致し" +"ません。" -#: ../source/specifications/binary-distribution-format.rst:219 -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/overview.rst:205 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 " -"layout offers a superset of the functionality provided by the existing " -"wininst and egg binary formats." +"If you're developing software that will be deployed to machines you own, " +"users' personal computers, or any other arrangement, read on." msgstr "" -"このバージョンの wheel 仕様は、distutils のインストール方法論に基づいていて、" -"ファイルを他の場所にインストールする方法については定義していません。既存の " -"wininst や egg バイナリフォーマットが提供する機能の上位互換のレイアウトを提案" -"します。" +"自分の機材やユーザのパーソナルコンピュータやその他の機材に配置することを想定" +"するソフトウェアを開発しているのであれば、このまま読み進めてください。" -#: ../source/specifications/binary-distribution-format.rst:226 -#: ../source/specifications/recording-installed-packages.rst:23 -#: ../source/specifications/binary-distribution-format.rst:228 -msgid "The .dist-info directory" -msgstr ".dist-info ディレクトリ" +#: ../source/overview.rst:209 +msgid "Web browsers and mobile applications" +msgstr "ウェブブラウザとモバイルアプリケーション" -#: ../source/specifications/binary-distribution-format.rst:228 -#: ../source/specifications/binary-distribution-format.rst:230 +#: ../source/overview.rst:211 msgid "" -"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " -"RECORD." +"Python's steady advances are leading it into new spaces. These days you can " +"write a mobile app or web application frontend in Python. While the language " +"may be familiar, the packaging and deployment practices are brand new." msgstr "" -"Wheel の .dist-info ディレクトリは、最低限でも METADATA ・ WHEEL ・RECORD を" -"含みます。" +"Python は着実に前進して新しい世界に突入しています。最近では、モバイルアプリや" +"ウェブアプリケーションのフロントエンドを Python で書くことができるようになっ" +"ています。言語自体には慣れていても、パッケージングや配置の実務は全く新しいも" +"のになっています。" -#: ../source/specifications/binary-distribution-format.rst:230 -#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/overview.rst:216 msgid "" -"METADATA is the package metadata, the same format as PKG-INFO as found at " -"the root of sdists." +"If you're planning on releasing to these new frontiers, you'll want to check " +"out the following frameworks, and refer to their packaging guides:" +msgstr "" +"このような新しい未開拓分野でリリースを計画しているのであれば、以下のフレーム" +"ワークに興味が湧いて、それぞれのパッケージングガイドを参照したくなるかもしれ" +"ません。" + +#: ../source/overview.rst:220 +msgid "`Kivy `_" msgstr "" -"METADATA はパッケージのメタデータで、 sdists のルートディレクトリにある PKG-" -"INFO と同じフォーマットで記述されます。" -#: ../source/specifications/binary-distribution-format.rst:232 -#: ../source/specifications/binary-distribution-format.rst:234 -msgid "WHEEL is the wheel metadata specific to a build of the package." +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "`Beeware `_" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "`Brython `_" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" msgstr "" -"WHEEL は、パッケージをビルドする部分に特化した wheel のメタデータです。" -#: ../source/specifications/binary-distribution-format.rst:233 -#: ../source/specifications/binary-distribution-format.rst:235 +#: ../source/overview.rst:225 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 " -"hash of itself, must include its hash. The hash algorithm must be sha256 or " -"better; specifically, md5 and sha1 are not permitted, as signed wheel files " -"rely on the strong hashes in RECORD to validate the integrity of the archive." +"If you are *not* interested in using a framework or platform, or just wonder " +"about some of the technologies and techniques utilized by the frameworks " +"above, continue reading below." msgstr "" -"RECORD は、 wheel に含まれる (ほとんど) 全てのファイルとそのセキュアなハッ" -"シュ値のリストです。 PEP 376 とは異なり、自分自身のハッシュ値を内包することは" -"不可能な RECORD を除く各ファイルのハッシュ値が含まれていなければなりません。" -"署名済みの wheel ファイルがアーカイブの完全性を検証するのに RECORD 内の暗号学" -"的に強いハッシュ値に依存しているので、ハッシュ計算のアルゴリズムは sha256 以" -"上でなければならず、特に md5 とsha1 は許されません。" +"フレームワークやプラットフォームに興味がなければ、あるいは、上記のフレーム" +"ワークが利用している技術や手練手管について不思議に思うのであれば、このまま読" +"み進めてください。" -#: ../source/specifications/binary-distribution-format.rst:239 -#: ../source/specifications/binary-distribution-format.rst:241 -msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." -msgstr "PEP 376 の INSTALLER と REQUESTED はアーカイブに含まれません。" +#: ../source/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "インストール済みの Python に依存する" -#: ../source/specifications/binary-distribution-format.rst:240 -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/overview.rst:232 msgid "" -"RECORD.jws is used for digital signatures. It is not mentioned in RECORD." +"Pick an arbitrary computer, and depending on the context, there's a very " +"good chance Python is already installed. Included by default in most Linux " +"and Mac operating systems for many years now, you can reasonably depend on " +"Python preexisting in your data centers or on the personal machines of " +"developers and data scientists." msgstr "" -"RECORD.jws は、デジタル署名のために使われます。これについては RECORD では触れ" -"られません。" +"任意のコンピュータを選んだ時に、もちろんその環境にもよりますが、 Python が既" +"にインストールされている確率は相当に高いでしょう。 Linux や Mac オペレーティ" +"ングシステムではもう多年にわたってデフォルトでインストールされているので、" +"データセンタの機材や、開発者やデータ科学者の個人用の機材には Python が入って" +"いるものと思っても構わないでしょう。" -#: ../source/specifications/binary-distribution-format.rst:242 -#: ../source/specifications/binary-distribution-format.rst:244 -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 "" -"自分の wheel ファイルを S/MIME 署名でセキュアにすることを好む人は、 RECORD." -"p7s を使うことができます。これについては RECORD では触れられません。" +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "このモデルを支える技術:" -#: ../source/specifications/binary-distribution-format.rst:245 -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr ":gh:`PEX ` (Python EXecutable)" + +#: ../source/overview.rst:241 msgid "" -"During extraction, wheel installers verify all the hashes in RECORD against " -"the file contents. Apart from RECORD and its signatures, installation will " -"fail if any file in the archive is not both mentioned and correctly hashed " -"in RECORD." +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" msgstr "" -"展開中に wheel インストーラは RECORD 内のハッシュ値と実際のファイルの内容 (の" -"ハッシュ値) をすべて検証します。 RECORD とその署名による検証に加えて、アーカ" -"イブの中のいずれかのファイルが RECORD にリストされていないか、または、正しく" -"ハッシュされていない時にはインストールがフェイルするでしょう。" +":doc:`zipapp ` (依存関係を管理する助けにはならない。" +"Python 3.5+ が必要。)" -#: ../source/specifications/binary-distribution-format.rst:252 -#: ../source/specifications/binary-distribution-format.rst:254 -msgid "The .data directory" -msgstr ".data ディレクトリ" +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr ":gh:`shiv ` (Python 3 が必要)" -#: ../source/specifications/binary-distribution-format.rst:254 -#: ../source/specifications/binary-distribution-format.rst:256 +#: ../source/overview.rst:244 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::" +"Of all the approaches here, depending on a pre-installed Python relies the " +"most on the target environment. Of course, this also makes for the smallest " +"package, as small as single-digit megabytes, or even kilobytes." msgstr "" -"site-packages 内に通常通りにインストールされなかったファイルはどれでも、." -"dist-info ディレクトリと同様に命名されるが .data/ 拡張子をつけられて .data " -"ディレクトリに行きます::" +"ここでのすべてのアプローチでは、ほとんどのインストール先となる環境にインス" +"トール済みの Python があるものと当てにしています。もちろん、これは、一桁メガ" +"バイト規模やさらにはキロバイト規模の最小のパッケージを作ることになります。" -#: ../source/specifications/binary-distribution-format.rst:262 -#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/overview.rst:249 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." +"In general, decreasing the dependency on the target system increases the " +"size of our package, so the solutions here are roughly arranged by " +"increasing size of output." msgstr "" -".data ディレクトリでは、配布物からのスクリプト・ヘッダー・説明文書などをサブ" -"ディレクトリに収めています。インストール中に、これらのサブディレクトリの内容" -"を行き先となるパスへ動かします。" +"一般に、インストール先の環境に対する依存を減少させるとパッケージ側のサイズは" +"大きくなるので、ここで述べる解決策は、おおまかに出力となるパッケージのサイズ" +"の増える順番に整理しています。" -#: ../source/specifications/binary-distribution-format.rst:268 -#: ../source/specifications/binary-distribution-format.rst:270 -msgid "Signed wheel files" -msgstr "署名済み wheel ファイル" +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "個別のソフトウェア配布エコシステムに依存する" -#: ../source/specifications/binary-distribution-format.rst:270 -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/overview.rst:258 msgid "" -"Wheel files include an extended RECORD that enables digital signatures. PEP " -"376's RECORD is altered to include a secure hash " -"``digestname=urlsafe_b64encode_nopad(digest)`` (urlsafe base64 encoding with " -"no trailing = characters) as the second column instead of an md5sum. All " -"possible entries are hashed, including any generated files such as .pyc " -"files, but not RECORD which cannot contain its own hash. For example::" +"For a long time many operating systems, including Mac and Windows, lacked " +"built-in package management. Only recently did these OSes gain so-called " +"\"app stores\", but even those focus on consumer applications and offer " +"little for developers." msgstr "" -"Wheel ファイルは、デジタル署名を可能にした拡張 RECORD ファイルを含みます。 " -"PEP 376 の RECORD は、 md5sum の代わりにセキュアなハッシュ値 " -"``digestname=urlsafe_b64encode_nopad(digest)`` (末尾に = 文字を追加しない " -"url セーフな base64 エンコード) を二つ目のカラムとするように修正されました。" -"生成された .pyc ファイルなども含むすべての可能なエントリにハッシュ値が付加さ" -"れていますが、 RECORD は自身のハッシュ値を含むことができないので例外です。例" -"えば::" +"長い間、Mac や Windows を含むさまざまなオペレーティングシステムは、組み込みの" +"パッケージ管理システムを欠いてきました。ごく最近になって、これらの OS にも所" +"謂「アプリストア (app stores)」が追加されましたが、しかし、まだ消費者向けのア" +"プリケーションを扱っているだけであり、開発者の役に立つものは少ないのが現状で" +"す。" -#: ../source/specifications/binary-distribution-format.rst:281 -#: ../source/specifications/binary-distribution-format.rst:283 +#: ../source/overview.rst:263 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 " -"file in the archive must have a correct hash in RECORD or the installation " -"will fail." +"Developers long sought remedies, and in this struggle, emerged with their " +"own package management solutions, such as `Homebrew `_. " +"The most relevant alternative for Python developers is a package ecosystem " +"called `Anaconda `_. Anaconda is built around Python and is " +"increasingly common in academic, analytical, and other data-oriented " +"environments, even making its way `into server-oriented environments " +"`_." msgstr "" -"署名用のファイルである RECORD.jws と RECORD.p7s は、 RECORD ファイルが作成さ" -"れた後にしか追加できないので、RECORD ファイル内で言及されることは全くありませ" -"ん。アーカイブの中の他のファイルはすべて、RECORD ファイル内に正しいハッシュ値" -"を持たなければならず、そうでなければインストールに失敗します。" +"長い間、開発者が解決方法を探し求めてきており、この格闘の中から `Homebrew " +"`_ のような独自のパッケージ管理手法が勃興した。 Python 開発" +"者にとっての最も適切な代替方法は、 `Anaconda `_ と呼ばれるパッケージエコシステムです。 " +"Anaconda は Python を中核として作成されており、学術や分析やデータ主導の環境で" +"より一層一般的になってきていて、`サーバ中心の環境に `_ さえ入り込んでいます。" -#: ../source/specifications/binary-distribution-format.rst:286 -#: ../source/specifications/binary-distribution-format.rst:288 +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "Anaconda エコシステム向けにビルドし公開するための指示書き:" + +#: ../source/overview.rst:275 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:" +"`Building libraries and applications with conda `_" msgstr "" -"JSON ウェブ署名が使われる場合には、ひとつかそれ以上の JSON Web Signature " -"JSON Serialization (JWS-JS) 署名が RECORD ファイルの隣にある RECORD.jws ファ" -"イルの中に保存されます。 RECORD ファイルの SHA-256 ハッシュ値を署名の JSON ペ" -"イロードに含むことで RECORD ファイルに署名するために JWS が使われます:" - -#: ../source/specifications/binary-distribution-format.rst:295 -#: ../source/specifications/binary-distribution-format.rst:297 -msgid "(The hash value is the same format used in RECORD.)" -msgstr "(ハッシュ値の書き方のフォーマットは RECORD で使われるものと同じです。)" +"`conda でライブラリやアプリケーションをビルドする `_" -#: ../source/specifications/binary-distribution-format.rst:297 -#: ../source/specifications/binary-distribution-format.rst:299 +#: ../source/overview.rst:276 msgid "" -"If RECORD.p7s is used, it must contain a detached S/MIME format signature of " -"RECORD." +"`Transitioning a native Python package to Anaconda `_" msgstr "" -"RECORD.p7s を使う場合は、このファイルに RECORD ファイルに関する分離型の S/" -"MIME 署名を入れておかなければなりません。" +"`Python 由来のパッケージを Anaconda へ移行する `_" -#: ../source/specifications/binary-distribution-format.rst:300 -#: ../source/specifications/binary-distribution-format.rst:302 +#: ../source/overview.rst:278 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 " -"installer checks file hashes against RECORD, a separate signature checker " -"only needs to establish that RECORD matches the signature." +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" msgstr "" -"wheel インストーラはデジタル署名を理解することを要求されてはいませんが、 " -"RECORD ファイル内のハッシュ値が展開されたファイル内容に対して妥当であることを" -"検証しなければなりません。インストーラが RECORD ファイルに対するハッシュ値を" -"確認する際には、別途用意された署名検証プログラムは RECORD ファイルが署名に対" -"して妥当であることだけを確認すれば十分です。" - -#: ../source/specifications/binary-distribution-format.rst:305 -#: ../source/specifications/binary-distribution-format.rst:307 -msgid "See" -msgstr "以下を参照のこと" - -#: ../source/specifications/binary-distribution-format.rst:307 -#: ../source/specifications/binary-distribution-format.rst:309 -msgid "https://datatracker.ietf.org/doc/html/rfc7515" -msgstr "https://datatracker.ietf.org/doc/html/rfc7515" +"よく似たモデルが Python 配布物の代替物をインストールする際にも適用されます" +"が、オペレーティングシステムレベルのパッケージはサポートしていません。" -#: ../source/specifications/binary-distribution-format.rst:308 -#: ../source/specifications/binary-distribution-format.rst:310 +#: ../source/overview.rst:282 msgid "" -"https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" -"serialization-01" +"`ActiveState ActivePython `_" msgstr "" -"https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" -"serialization-01" +"`ActiveState ActivePython `_" -#: ../source/specifications/binary-distribution-format.rst:309 -#: ../source/specifications/binary-distribution-format.rst:311 -msgid "https://datatracker.ietf.org/doc/html/rfc7517" -msgstr "https://datatracker.ietf.org/doc/html/rfc7517" +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "`WinPython `_" -#: ../source/specifications/binary-distribution-format.rst:310 -#: ../source/specifications/binary-distribution-format.rst:312 +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "自分の Python 実行形式を持ち込む" + +#: ../source/overview.rst:290 msgid "" -"https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" +"Computing as we know it is defined by the ability to execute programs. Every " +"operating system natively supports one or more formats of programs they can " +"natively execute." msgstr "" -"https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" - -#: ../source/specifications/binary-distribution-format.rst:314 -#: ../source/specifications/platform-compatibility-tags.rst:268 -#: ../source/specifications/binary-distribution-format.rst:316 -msgid "FAQ" -msgstr "FAQ" +"我々が知るところのコンピューティングは、プログラムを実行する能力として定義さ" +"れます。それぞれのオペレーティングシステムは、そのまま実行することが可能なひ" +"とつかもっと多くのプログラムフォーマットを元々サポートしています。" -#: ../source/specifications/binary-distribution-format.rst:318 -#: ../source/specifications/binary-distribution-format.rst:320 -msgid "Wheel defines a .data directory. Should I put all my data there?" +#: ../source/overview.rst:294 +msgid "" +"There are many techniques and technologies which turn your Python program " +"into one of these formats, most of which involve embedding the Python " +"interpreter and any other dependencies into a single executable file." msgstr "" -"Wheel は .data ディレクトリを定義します。すべてのデータをそこに入れるべきで" -"しょうか？" +"そのようなフォーマットにあなたの Python プログラムを変換する数多くの手練手管" +"や技術が存在していて、そのほとんどでは Python インタープリタやその他の依存先" +"を単一の実行形式のファイルに組み込むことになるでしょう。" -#: ../source/specifications/binary-distribution-format.rst:320 -#: ../source/specifications/binary-distribution-format.rst:322 +#: ../source/overview.rst:299 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." +"This approach, called *freezing*, offers wide compatibility and seamless " +"user experience, though often requires multiple technologies, and a good " +"amount of effort." msgstr "" -"この仕様では、あなたがあなたのソースコードをどのように組織立てて置くべきかに" -"ついては特に意見を表明していません。 .data ディレクトリは、 ``site-" -"packages`` 内や PYTHONPATH 内に通常ならインストールされない全てのファイルを置" -"く場所というだけのことです。換言すれば、 *そのような* ファイル群が通常なら " -"*wheel の* ``.data`` ディレクトリに置く形で配布されない時でさえも、 " -"``pkgutil.get_data(package, resource)`` を使い続けても構わないのです。" +"*フリージング* と呼ばれるこの方法論は、しばしば複数の技術と共にかなりの努力を" +"要求しますが、幅広い互換性と継ぎ目のないユーザ経験を提供します。" -#: ../source/specifications/binary-distribution-format.rst:329 -#: ../source/specifications/binary-distribution-format.rst:331 -msgid "Why does wheel include attached signatures?" -msgstr "なぜ wheel は添付された署名を持つのか？" +#: ../source/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "Python フリーザの選択肢:" -#: ../source/specifications/binary-distribution-format.rst:331 -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/overview.rst:305 msgid "" -"Attached signatures are more convenient than detached signatures because " -"they travel with the archive. Since only the individual files are signed, " -"the archive can be recompressed without invalidating the signature or " -"individual files can be verified without having to download the whole " -"archive." +"`pyInstaller `_ - Cross-" +"platform" msgstr "" -"添付された署名は、アーカイブと一体のものとして転送されるので、分離署名よりも" -"便利です。個々のファイルが署名されているだけなので、アーカイブを圧縮し直して" -"も署名が無効にならず、また、アーカイブ全体をダウンロードしなくても個々のファ" -"イルの検証を行うことができます。" - -#: ../source/specifications/binary-distribution-format.rst:339 -#: ../source/specifications/binary-distribution-format.rst:341 -msgid "Why does wheel allow JWS signatures?" -msgstr "なぜ wheel は JWS 署名を許容するのか？" +"`pyInstaller `_ - クロスプラッ" +"トフォーム" -#: ../source/specifications/binary-distribution-format.rst:341 -#: ../source/specifications/binary-distribution-format.rst:343 +#: ../source/overview.rst:306 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." +"`cx_Freeze `_ - Cross-platform" msgstr "" -"JWS がその一部を構成する JOSE の仕様は実装を容易にするように設計されており、" -"その性質は wheel の基本的な設計目標のひとつでもあります。 JWS は使いやすくて" -"簡潔な純 Python の実装をもたらします。" - -#: ../source/specifications/binary-distribution-format.rst:347 -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "Why does wheel also allow S/MIME signatures?" -msgstr "なぜ wheel は S/MIME 署名をも許容するのか？" +"`cx_Freeze `_ - クロスプラット" +"フォーム" -#: ../source/specifications/binary-distribution-format.rst:349 -#: ../source/specifications/binary-distribution-format.rst:351 +#: ../source/overview.rst:307 msgid "" -"S/MIME signatures are allowed for users who need or want to use existing " -"public key infrastructure with wheel." +"`constructor `_ - For command-line " +"installers" msgstr "" -"S/MIME 署名は、既存の公開鍵基盤を wheel でも採用する必要があるか、または、採" -"用したいユーザのために許容されています。" +"`constructor `_ - コマンドラインインス" +"トーラ向け" -#: ../source/specifications/binary-distribution-format.rst:352 -#: ../source/specifications/binary-distribution-format.rst:354 +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "`py2exe `_ - Windows 限定" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "`py2app `_ - Mac 限定" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "`osnap `_ - Windows と Mac" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "`pynsist `_ - Windows 限定" + +#: ../source/overview.rst:313 msgid "" -"Signed packages are only a basic building block in a secure package update " -"system. Wheel only provides the building block." +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." msgstr "" -"署名されたパッケージは、セキュアなパッケージ更新システムを構成するひとつのビ" -"ルディングブロックであるというだけのものです。 Wheel としては、単にビルディン" -"グブロックを提供するだけです。" +"上記のものはほとんどが単独のユーザでの配置です。複数部分から構成されるサーバ" +"アプリケーション向けには :gh:`Chef Omnibus ` を見てください。" -#: ../source/specifications/binary-distribution-format.rst:357 -#: ../source/specifications/binary-distribution-format.rst:359 -msgid "What's the deal with \"purelib\" vs. \"platlib\"?" -msgstr "\"pure lib\" と \"plat lib\" って、どう扱えばいいの？" +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "自分自身のユーザスペースを持ち込む" -#: ../source/specifications/binary-distribution-format.rst:359 -#: ../source/specifications/binary-distribution-format.rst:361 +#: ../source/overview.rst:321 msgid "" -"Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " -"significant on some platforms. For example, Fedora installs pure Python " -"packages to '/usr/lib/pythonX.Y/site-packages' and platform dependent " -"packages to '/usr/lib64/pythonX.Y/site-packages'." +"An increasing number of operating systems -- including Linux, Mac OS, and " +"Windows -- can be set up to run applications packaged as lightweight images, " +"using a relatively modern arrangement often referred to as `operating-system-" +"level virtualization `_, or *containerization*." msgstr "" -"Wheel は \"purelib\" と \"platlib\" を区別して扱いますが、これらはプラット" -"フォームによっては大きな違いがあります。例えば、 Fedora では純 Python のパッ" -"ケージを '/usr/lib/pythonX.Y/site-packages' にインストールし、プラットフォー" -"ムに依存しないパッケージを '/usr/lib64/pythonX.Y/site-packages' にインストー" -"ルします。" +"オペレーティングシステム -- Linux や Mac OS や Windows を含む -- で、しばし" +"ば `オペレーティングシステムレベルの仮想化 `_ もしくは *コンテナ化* として参照され" +"る相対的に新しい手法を用いた、軽量のイメージとしてパッケージされたアプリケー" +"ションを走らせるように設定することができるものが数を増しています。" -#: ../source/specifications/binary-distribution-format.rst:364 -#: ../source/specifications/binary-distribution-format.rst:366 +#: ../source/overview.rst:328 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: " -"true\" with those same files in the root, and it is legal to have files in " -"both the \"purelib\" and \"platlib\" categories." +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." msgstr "" -"``{name}-{version}.data/purelib`` 内の全てのファイルについて \"Root-Is-" -"Purelib: false\" という設定になっている wheel ファイルは、同じファイルがルー" -"トディレクトリ内にあって \"Root-Is-Purelib: true\" になっている wheel ファイ" -"ルと相同であり、 \"purelib\" と \"platlib\" の両カテゴリにファイル群が存在す" -"ることには問題がありません。" +"このような手法は Python 単体もしくは Python パッケージではなく OS のファイル" +"システム全体をパッケージ化するので、ほとんどの場合には Python を直接にサポー" +"トしているわけではありません。" -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/binary-distribution-format.rst:371 +#: ../source/overview.rst:331 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\"." +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" msgstr "" -"実際のところ、 wheel は、それが純 Python なのかそうでないのかによって " -"\"purelib\" または \"platlib\" のいずれか一方しか持たず、 \"Root-Is-" -"purelib\" を適切に設定しつつファイル群をルートディレクトリに置くべきです。" +"(訳注、このような技術の) 取り入れが最も広範囲に渡るのは、この技術の発祥の地で" +"あり下に述べる技術が最もうまく動作する Linux サーバです:" -#: ../source/specifications/binary-distribution-format.rst:377 -#: ../source/specifications/binary-distribution-format.rst:379 -msgid "Is it possible to import Python code directly from a wheel file?" -msgstr "" -"Python のソースコードを wheel ファイルから直接にインポートすることはできます" -"か？" +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "`AppImage `_" -#: ../source/specifications/binary-distribution-format.rst:379 -#: ../source/specifications/binary-distribution-format.rst:381 +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "`Docker `_" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "`Flatpak `_" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "`Snapcraft `_" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "自分自身のカーネルを持ち込む" + +#: ../source/overview.rst:342 msgid "" -"Technically, due to the combination of supporting installation via simple " -"extraction and using an archive format that is compatible with " -"``zipimport``, a subset of wheel files *do* support being placed directly on " -"``sys.path``. However, while this behaviour is a natural consequence of the " -"format design, actually relying on it is generally discouraged." +"Most operating systems support some form of classical virtualization, " +"running applications packaged as images containing a full operating system " +"of their own. Running these virtual machines, or VMs, is a mature approach, " +"widespread in data center environments." msgstr "" -"技術的な話としては、単純に展開するだけでインストールできる機能と " -"``zipimport`` と互換性のあるアーカイブフォーマットの両方をサポートしているの" -"で、一部の wheel ファイルは ``sys.path`` に直接に置くことを *サポートしていま" -"す* 。しかし、このような動作はフォーマット設計の自然な結果とはいうものの、実" -"際にはこれに依存することは一般的には推奨されていません。" +"ほとんどのオペレーティングシステムでは、何らかの形であるオペレーティングシス" +"テム全体を内包するイメージの形にパッケージされたアプリケーションを動作させる" +"ことができるような、古典的な仮想化がサポートされています。このような仮想マシ" +"ンもしくは VM を動作させることは枯れた方法論で、データセンタ環境に広く普及し" +"ています。" -#: ../source/specifications/binary-distribution-format.rst:385 -#: ../source/specifications/binary-distribution-format.rst:387 +#: ../source/overview.rst:347 msgid "" -"Firstly, wheel *is* designed primarily as a distribution format, so skipping " -"the installation step also means deliberately avoiding any reliance on " -"features that assume full installation (such as being able to use standard " -"tools like ``pip`` and ``virtualenv`` to capture and manage dependencies in " -"a way that can be properly tracked for auditing and security update " -"purposes, or integrating fully with the standard build machinery for C " -"extensions by publishing header files in the appropriate place)." +"These techniques are mostly reserved for larger scale deployments in data " +"centers, though certain complex applications can benefit from this " +"packaging. The technologies are Python agnostic, and include:" msgstr "" -"第一に、wheel は一義的に配布物のフォーマットとして *設計されている* ので、イ" -"ンストールの段階を省略するということは、完全なインストールがなされているもの" -"と仮定している機能 (例えば、正当性監査やセキュリティアップデートのために正し" -"く追跡することができるひとつの方法であるところの ``pip`` や ``virtualenv`` の" -"ような標準ツールを使った依存関係の捕捉や管理の機能、あるいは、ヘッダファイル" -"を適切な場所に公開することによって C 言語拡張をビルドする標準的な機構を完全に" -"統合する機能) への信頼を故意に避けることになります。" +"複雑なアプリケーションの中にはこのパッケージング方法から利益を得るものもあり" +"ますが、このような手法はたいていの場合はデータセンタにおけるかなり大規模な配" +"置のために使用します。技術としては Python を直接サポートしているわけではな" +"く、次のものを含みます:" + +#: ../source/overview.rst:351 +msgid "`Vagrant `_" +msgstr "`Vagrant `_" -#: ../source/specifications/binary-distribution-format.rst:394 -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/overview.rst:352 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 " -"has been fully installed. When that assumption is broken by trying to run " -"the software from a zip archive, the failures can often be obscure and hard " -"to diagnose (especially when they occur in third party libraries). The two " -"most common sources of problems with this are the fact that importing C " -"extensions from a zip archive is *not* supported by CPython (since doing so " -"is not supported directly by the dynamic loading machinery on any platform) " -"and that when running from a zip archive the ``__file__`` attribute no " -"longer refers to an ordinary filesystem path, but to a combination path that " -"includes both the location of the zip archive on the filesystem and the " -"relative path to the module inside the archive. Even when software correctly " -"uses the abstract resource APIs internally, interfacing with external " -"components may still require the availability of an actual on-disk file." +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" msgstr "" -"第二に、 Python のソフトウェアの中には zip アーカイブから直接に動作させること" -"をサポートするように書かれているものもありますが、やはり完全にインストールさ" -"れることを前提にして書かれたソースコードが今も普通です。 zip アーカイブからソ" -"フトウェアを走らせようと試みてこの仮定を崩すと、 (とりわけ失敗動作がサード" -"パーティのライブラリで起きる場合には) しばしば失敗動作がわかりにくく原因究明" -"が困難になるでしょう。この問題の最もありがちなふたつの根源は、 C 言語拡張を " -"zip アーカイブからインポートすることが CPython では *サポートされていない* こ" -"と (というのは、どんなプラットフォームの動的ローディング機構でもこのような動" -"作が直接にはサポートされていないから) 、および、 zip アーカイブから動作する際" -"には ``__file__`` 属性がもはや普通のファイルシステム上のファイルパスを参照し" -"ておらず、 zip アーカイブのファイルシステム上の置き場所のパスとアーカイブ内の" -"モジュールへの相対パスの両方を含んだ連結パスになることです。ソフトウェア内で" -"は抽象化された資源への API 群を正しく扱えたとしても、外部の部品とのインタフェ" -"イスは依然として実際にディスク上に存在するファイルがないと動作できないかもし" -"れません。" +"`VHD `_ や `AMI `_ や :doc:`他のフォーマット " +"`" -#: ../source/specifications/binary-distribution-format.rst:411 -#: ../source/specifications/binary-distribution-format.rst:413 +#: ../source/overview.rst:353 msgid "" -"Like metaclasses, monkeypatching and metapath importers, if you're not " -"already sure you need to take advantage of this feature, you almost " -"certainly don't need it. If you *do* decide to use it anyway, be aware that " -"many projects will require a failure to be reproduced with a fully installed " -"package before accepting it as a genuine bug." +"`OpenStack `_ - A cloud " +"management system in Python, with extensive VM support" msgstr "" -"メタクラスと同様に、モンキーパッチングとメタパスからのインポートは、この機能" -"を使う利点をあなたが本当に必要としていると確信しているのでなければ、おそらく" -"あなたはこの機能を使う必要がないと思われます。兎にも角にもこれを使う *意思を" -"固めた* のであれば、 (訳注、この機能を使った時に生じた) ある動作不良を真性の" -"バグであると認めてもらう前に、多くのプロジェクトではそれを完全インストールの" -"状態で再現するように要求されるであろうということを認識しておいてください。" - -#: ../source/specifications/binary-distribution-format.rst:419 -#: ../source/specifications/core-metadata.rst:848 -#: ../source/specifications/dependency-specifiers.rst:476 -#: ../source/specifications/direct-url-data-structure.rst:392 -#: ../source/specifications/direct-url.rst:67 -#: ../source/specifications/entry-points.rst:164 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:211 -#: ../source/specifications/name-normalization.rst:50 -#: ../source/specifications/platform-compatibility-tags.rst:332 -#: ../source/specifications/pyproject-toml.rst:442 -#: ../source/specifications/recording-installed-packages.rst:252 -#: ../source/specifications/simple-repository-api.rst:974 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1264 -#: ../source/specifications/virtual-environments.rst:54 -#: ../source/specifications/binary-distribution-format.rst:421 -msgid "History" -msgstr "歴史" +"`OpenStack `_ - 大規模な VM サ" +"ポート機能がついていて Python で書かれたクラウド管理システム" -#: ../source/specifications/binary-distribution-format.rst:421 -#: ../source/specifications/binary-distribution-format.rst:423 -msgid "February 2013: This specification was approved through :pep:`427`." -msgstr "2013年2月: :pep:`427` を通じてこの仕様書が承認されました。" +#: ../source/overview.rst:356 +msgid "Bringing your own hardware" +msgstr "自分自身のハードウェアを持ち込む" -#: ../source/specifications/binary-distribution-format.rst:422 -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/overview.rst:358 msgid "" -"February 2021: The rules on escaping in wheel filenames were revised, to " -"bring them into line with what popular tools actually do." +"The most all-encompassing way to ship your software would be to ship it " +"already-installed on some hardware. This way, your software's user would " +"require only electricity." msgstr "" -"2021年2月: 他の普及しているツールが実際にやるのと同じやり方に合わせて、 " -"wheel のファイル名におけるエスケーピングの規則が修正されました。" +"最もすべてを包含した方法は、あなたのソフトウェアを何らかのハードウェア上にイ" +"ンストールして出荷することです。この方法では、あなたのソフトウェアのユーザは" +"電力供給しか要求されません。" -#: ../source/specifications/binary-distribution-format.rst:427 -#: ../source/specifications/binary-distribution-format.rst:429 -msgid "Appendix" -msgstr "補遺" +#: ../source/overview.rst:362 +msgid "" +"Whereas the virtual machines described above are primarily reserved for the " +"tech-savvy, you can find hardware appliances being used by everyone from the " +"most advanced data centers to the youngest children." +msgstr "" +"上で述べた仮想マシンがもっぱら技術に明るい人向けであるのに対し、ハードウェア" +"によるアプライアンス機器は最先端のデータセンタから最も若い子供たちまでの誰に" +"でも使えます。" -#: ../source/specifications/binary-distribution-format.rst:429 -#: ../source/specifications/binary-distribution-format.rst:431 -msgid "Example urlsafe-base64-nopad implementation::" -msgstr "urlsafe-base64-nopad の実装の例::" +#: ../source/overview.rst:366 +msgid "" +"Embed your code on an :gh:`Adafruit `, `MicroPython " +"`_, or more-powerful hardware running Python, then " +"ship it to the datacenter or your users' homes. They plug and play, and you " +"can call it a day." +msgstr "" +":gh:`Adafruit ` や `MicroPython `_ 、あるいは、もっとパワーのあるハードウェアで Python が動作するものに" +"あなたのプログラムを組み込んで、データセンタやあなたのユーザの家に出荷しま" +"しょう。彼らはプラグアンドプレイで使うし、あなたはその日の仕事を終わりにでき" +"るでしょう。" -#: ../source/specifications/core-metadata.rst:7 -msgid "Core metadata specifications" -msgstr "コアとなるメタデータの仕様" +#: ../source/overview.rst:375 +msgid "A summary of technologies used to package Python applications." +msgstr "Python アプリケーションをパッケージするのに使われる技術の概要。" -#: ../source/specifications/core-metadata.rst:9 +#: ../source/overview.rst:375 msgid "" -"Fields defined in the following specification should be considered valid, " -"complete and not subject to change. The required fields are:" +"The simplified gamut of technologies used to package Python applications." msgstr "" -"この後の仕様の中で定義されるフィールドは、正当かつ完全であって、変更の可能性" -"がないものと見做されるべきです。必須のフィールドは以下の通り:" +"Python アプリケーションをパッケージするのに使われる技術の単純化された全体像。" -#: ../source/specifications/core-metadata.rst:12 -msgid "``Metadata-Version``" +#: ../source/overview.rst:378 +msgid "What about..." +msgstr "これは何..." + +#: ../source/overview.rst:380 +msgid "" +"The sections above can only summarize so much, and you might be wondering " +"about some of the more conspicuous gaps." msgstr "" +"上記の節ではかなり要約して書いているので、飛躍している点が目につくかもしれま" +"せん。" -#: ../source/specifications/core-metadata.rst:13 -msgid "``Name``" -msgstr "``Name``" +#: ../source/overview.rst:384 +msgid "Operating system packages" +msgstr "オペレーティングシステムレベルのパッケージ" -#: ../source/specifications/core-metadata.rst:14 -msgid "``Version``" +#: ../source/overview.rst:386 +msgid "" +"As mentioned in :ref:`depending-on-a-separate-ecosystem` above, some " +"operating systems have package managers of their own. If you're very sure of " +"the operating system you're targeting, you can depend directly on a format " +"like `deb `_ (for Debian, " +"Ubuntu, etc.) or `RPM `_ " +"(for Red Hat, Fedora, etc.), and use that built-in package manager to take " +"care of installation, and even deployment. You can even use `FPM `_ to generate " +"both deb and RPMs from the same source." msgstr "" +"上記の :ref:`depending-on-a-separate-ecosystem` で言及したように、オペレー" +"ティングシステムの中には独自のパッケージ管理機構を備えているものがあります。" +"あなたがターゲットにするオペレーティングシステムが非常にはっきりわかっている" +"なら、 `deb `_ (Debian や " +"Ubuntu その他向け。) か、 `RPM `_ (Red Hat や Fedora その他向け。) のようなフォーマット" +"を直接利用して、インストールや配置さえもその面倒を見るのに組み込みのパッケー" +"ジ管理機構を活用することができます。 `FPM `_ を使えば、同じソースコードから deb " +"と RPM の両方を生成することさえ可能です。" -#: ../source/specifications/core-metadata.rst:16 -msgid "All the other fields are optional." -msgstr "これら以外のすべてのフィールドは必須のものではありません。" +#: ../source/overview.rst:397 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" +"ほとんどの配置パイプラインでは、 OS パッケージ管理機構は全体から見ればほんの" +"一部です。" -#: ../source/specifications/core-metadata.rst:18 +#: ../source/overview.rst:403 msgid "" -"The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `) is based on the format of email headers. However, email formats " -"have been revised several times, and exactly which email RFC applies to " -"packaging metadata is not specified. In the absence of a precise definition, " -"the practical standard is set by what the standard library :mod:`python:" -"email.parser` module can parse using the :data:`~.python:email.policy." -"compat32` policy." +":doc:`Virtualenvs ` have been an indispensable " +"tool for multiple generations of Python developer, but are slowly fading " +"from view, as they are being wrapped by higher-level tools. With packaging " +"in particular, virtualenvs are used as a primitive in :doc:`the dh-" +"virtualenv tool ` and `osnap `_, both of which wrap virtualenvs in a self-contained way." msgstr "" -"(:doc:`wheels ` および :doc:`インストール済みのプ" -"ロジェクト ` の両文書に含まれる) メタデータのた" -"めの標準的なファイルフォーマットは、電子メールのヘッダーのフォーマットに基い" -"ています。しかしながら、電子メールのフォーマットは何度か修正が入っています" -"が、正確にはどの電子メールの RFC がパッケージングのメタデータに適用されるのか" -"については指定がありません。精密な定義が欠落しているので、標準ライブラリの :" -"mod:`python:email.parser` モジュールが :data:`~.python:email.policy." -"compat32` のポリシーを用いて読み込むことができるものを実務上の標準として設定" -"しています。" +":doc:`Virtualenvs ` は、複数世代の Python 向け" +"に開発をする者にとっては以前から避けられないツールであり続けてきたが、高レベ" +"ルのツール群がラップするようになったので徐々に見えなくなりつつあります。特に" +"パッケージングの観点では、共に virtualenvs を内包する形でラップしている :doc:" +"`the dh-virtualenv tool ` や `osnap `_ では virtualenvs はプリミティブとして使われています。" -#: ../source/specifications/core-metadata.rst:27 +#: ../source/overview.rst:412 msgid "" -"Whenever metadata is serialised to a byte stream (for example, to save to a " -"file), strings must be serialised using the UTF-8 encoding." +"For production deployments, do not rely on running ``python -m pip install`` " +"from the Internet into a virtualenv, as one might do in a development " +"environment. The overview above is full of much better solutions." msgstr "" -"メタデータをバイト列 (例えばファイルに保存するために) にシリアル化する際には" -"いつでも、文字列を UTF-8 エンコーディングを用いてシリアル化しなければなりませ" -"ん。" +"開発環境ではありがちですが、商用環境への配置ではインターネットから " +"virtualenv への ``python -m pip install`` を走らせることに信用をおいてはなり" +"ません。上に述べた概要には、より良い解決策がたくさんあります。" -#: ../source/specifications/core-metadata.rst:30 +#: ../source/overview.rst:417 +msgid "Security" +msgstr "セキュリティ" + +#: ../source/overview.rst:419 msgid "" -"Although :pep:`566` defined a way to transform metadata into a JSON-" -"compatible dictionary, this is not yet used as a standard interchange " -"format. The need for tools to work with years worth of existing packages " -"makes it difficult to shift to a new format." +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." msgstr "" -":pep:`566` でメタデータを JSON 互換の辞書型に変換する一つの方法を定義していま" -"すが、標準の交換フォーマットとしてはまだ使われていません。既に何年間も使われ" -"てきた既存のパッケージと共に動作するツールが必要なので、新しいフォーマットに" -"移行することは困難なのです。" +"あなたのパッケージの部品を更新することは、ここまで積み上げてきたものよりさら" +"に困難なものになるでしょう。あらゆるものがより緊密に互いに固着しているので" +"す。" -#: ../source/specifications/core-metadata.rst:35 +#: ../source/overview.rst:422 msgid "" -"*Interpreting old metadata:* In :pep:`566`, the version specifier field " -"format specification was relaxed to accept the syntax used by popular " -"publishing tools (namely to remove the requirement that version specifiers " -"must be surrounded by parentheses). Metadata consumers may want to use the " -"more relaxed formatting rules even for metadata files that are nominally " -"less than version 2.1." +"For example, if a kernel security issue emerges, and you're deploying " +"containers, the host system's kernel can be updated without requiring a new " +"build on behalf of the application. If you deploy VM images, you'll need a " +"new build. Whether or not this dynamic makes one option more secure is still " +"a bit of an old debate, going back to the still-unsettled matter of `static " +"versus dynamic linking `_." msgstr "" -"*古い形式のメタデータを翻訳する:* :pep:`566` では、バージョン指定子フィールド" -"のフォーマット仕様がよく用いられている公開ツール群で使われる構文を受け入れる " -"(正確にはバージョン指定子が丸括弧で囲まれていなければならないという要求事項を" -"削除することによって) ようにと緩められました。メタデータを使う側としては、メ" -"タデータファイルが名ばかりのものとなっている 2.1 よりも前のバージョンであって" -"さえも、もっと寛容なフォーマット規則を使いたいかもしれません。" +"例えば、仮にあなたがコンテナ型の仮想環境を配置していて、カーネルのセキュリ" +"ティ問題が発生したとすれば、アプリケーションに新たなビルドを要求することなく" +"ホスト側のカーネルが更新されるかもしれません。もしあなたが VM イメージを配置" +"しているなら、それを再ビルドする必要があるかもしれません。このような動的な挙" +"動をよりセキュアにするひとつのオプションは、以前から少々議論の的になっている" +"がまだ決着のついていない `静的リンク対動的リンク `_ ということになります。" -#: ../source/specifications/core-metadata.rst:46 -msgid "Metadata-Version" -msgstr "Metadata-Version" +#: ../source/overview.rst:431 +msgid "Wrap up" +msgstr "まとめ" -#: ../source/specifications/core-metadata.rst:50 +#: ../source/overview.rst:433 msgid "" -"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " -"\"2.1\", \"2.2\", and \"2.3\"." +"Packaging in Python has a bit of a reputation for being a bumpy ride. This " +"impression is mostly a byproduct of Python's versatility. Once you " +"understand the natural boundaries between each packaging solution, you begin " +"to realize that the varied landscape is a small price Python programmers pay " +"for using one of the most balanced, flexible languages available." msgstr "" -"ファイルフォーマットのバージョン; 正しいものは \"1.0\", \"1.1\", \"1.2\", " -"\"2.1\", \"2.2\", と \"2.3\"。" +"Python におけるパッケージングは、凸凹道を車で行くようなもので苦労が多いという" +"評判も少しあります。このような感想は、ほとんどの場合は Python が多用途に使え" +"ることの裏返しです。それぞれのパッケージング方法の間にある自然な境界線を理解" +"しさえすれば、さまざまに異なる風景が、もっともバランスが取れていて自由度の高" +"い言語を使うということのために Python プログラマが支払う小さな代償であること" +"に気づくことでしょう。" -#: ../source/specifications/core-metadata.rst:53 +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "バイナリ配布物のフォーマット" + +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"Automated tools consuming metadata SHOULD warn if ``metadata_version`` is " -"greater than the highest version they support, and MUST fail if " -"``metadata_version`` has a greater major version than the highest version " -"they support (as described in the :ref:`Version specifier specification " -"`, the major version is the value before the first dot)." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -"メタデータを処理する自動化ツールは、 ``metadata_version`` が自身のサポートす" -"る最大のものより大きい場合には警告を行うべきであり、かつ、 " -"``metadata_version`` が自身のサポートする最大のメジャーバージョンより大きいメ" -"ジャーバージョンを持つ場合には異常終了しなければなりません (:ref:`バージョン" -"指定子 ` に記述されている通り、メジャーバージョンとはバー" -"ジョンのうち最初のドットよりも前の部分です) 。" +"このページでは、Python パッケージのバイナリ配布物フォーマット、これは wheel " +"フォーマットとも呼ばれているものですが、これについて仕様を記述します。" -#: ../source/specifications/core-metadata.rst:60 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" -"For broader compatibility, build tools MAY choose to produce distribution " -"metadata using the lowest metadata version that includes all of the needed " -"fields." +"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 " +"installed according to PEP 376 with a particular installation scheme. " +"Although a specialized installer is recommended, a wheel file may be " +"installed by simply unpacking into site-packages with the standard 'unzip' " +"tool while preserving enough information to spread its contents out onto " +"their final paths at any later time." msgstr "" -"より広く互換性を保つために、ビルドツールは、必要なフィールドをすべて含む前提" -"で最も古いバージョンのメタデータ仕様を使って配布物のメタデータを生成するとい" -"う選択を行なっても構いません。" +"wheel は、特別にフォーマットされたファイル名と ``.whl`` 拡張子を持った ZIP " +"フォーマットのアーカイブです。 PEP 376 にほぼ従ってインストールされる単一の配" +"布物を含んでいます。特別なインストーラを使うことが推奨されていますが、 wheel " +"ファイルは、いつでも後でその最終的なパス名の場所に内容物を展開するに足りる情" +"報を保存しつつ、サイトパッケージを置くべき場所に標準の 'unxip' ツールで単純に" +"アンパックすればインストールできます。" -#: ../source/specifications/core-metadata.rst:64 -#: ../source/specifications/core-metadata.rst:82 -#: ../source/specifications/core-metadata.rst:99 -#: ../source/specifications/core-metadata.rst:164 -#: ../source/specifications/core-metadata.rst:179 -#: ../source/specifications/core-metadata.rst:217 -#: ../source/specifications/core-metadata.rst:289 -#: ../source/specifications/core-metadata.rst:293 -#: ../source/specifications/core-metadata.rst:297 -#: ../source/specifications/core-metadata.rst:301 -#: ../source/specifications/core-metadata.rst:333 -#: ../source/specifications/core-metadata.rst:354 -#: ../source/specifications/core-metadata.rst:381 -#: ../source/specifications/core-metadata.rst:399 -#: ../source/specifications/core-metadata.rst:424 -#: ../source/specifications/core-metadata.rst:446 -#: ../source/specifications/core-metadata.rst:609 -#: ../source/specifications/core-metadata.rst:640 -#: ../source/specifications/core-metadata.rst:650 -#: ../source/specifications/core-metadata.rst:842 -msgid "Example::" -msgstr "例::" +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "詳細" -#: ../source/specifications/core-metadata.rst:72 -msgid "Name" -msgstr "" +#: ../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/core-metadata.rst:75 -msgid "Added restrictions on format from the :ref:`name format `." -msgstr "" -":ref:`名称のフォーマット ` から採用したフォーマットに対する制限" -"を追加した。" +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "Wheel によるインストールは、概念上、ふたつの段階から構成されています:" -#: ../source/specifications/core-metadata.rst:78 +#: ../source/specifications/binary-distribution-format.rst:29 +msgid "Unpack." +msgstr "アンパックする。" + +#: ../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:32 msgid "" -"The name of the distribution. The name field is the primary identifier for a " -"distribution. It must conform to the :ref:`name format specification `." +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." msgstr "" -"配布物の名称。name フィールドは配布物の最も基本的な識別子です。 :ref:`名称" -"フォーマット仕様 ` を満たしていなければなりません。" +"インストーラが Wheel のバージョンと互換であることを確認します。マイナーバー" +"ジョンが大きければ警告し、メジャーバージョンが大きければ処理を中断します。" -#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" -"For comparison purposes, the names should be :ref:`normalized ` before comparing." +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -"比較の目的のためにも、名前は比較の前に :ref:`正規化 ` さ" -"れているべきです。" +"もし、 Root-Is-Purelib == 'true' であれば、アーカイブを purelib (site-" +"packages) へアンパックします。" -#: ../source/specifications/core-metadata.rst:91 -msgid "Version" +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." msgstr "" +"そうでなければ、アーカイブを platlib (site-packages) へアンパックします。" -#: ../source/specifications/core-metadata.rst:95 +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "広げる。" + +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" -"A string containing the distribution's version number. This field must be " -"in the format specified in the :ref:`Version specifier specification " -"`." +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." msgstr "" -"配布物のバージョン番号を格納する文字列。このフィールドは :ref:`バージョン指定" -"子仕様 ` で規定されるフォーマットでなければなりません。" - -#: ../source/specifications/core-metadata.rst:107 -msgid "Dynamic (multiple use)" -msgstr "Dyanamic (複数回の使用可)" +"アンパックされたアーカイブは、 ``distribution-1.0.dist-info/`` と (データ部分" +"があれば) ``distribution-1.0.data/`` を含んでいます。" -#: ../source/specifications/core-metadata.rst:111 +#: ../source/specifications/binary-distribution-format.rst:42 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." +"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 " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. The initially supported paths are taken from " +"``distutils.command.install``." msgstr "" -"別のコアとなるメタデータのフィールドの名前を包含した文字列。フィールド名の " -"``Name`` ・ ``Version`` ・ ``Metadata-Version`` をこのフィールドに指定しては" -"なりません。" +"``distribution-1.0.data/`` の下の全てのサブツリーを、その目的地となるディレク" +"トリパスに移動します。 ``distribution-1.0.data/(purelib|platlib|headers|" +"scripts|data)`` のような ``distribution-1.0.data/`` の下のそれぞれのサブディ" +"レクトリは、目的地となるディレクトリパスの辞書になっています。初期状態でサ" +"ポートされているパスは ``distutils.command.install`` から取り込まれます。" -#: ../source/specifications/core-metadata.rst:115 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" -"When found in the metadata of a source distribution, the following rules " -"apply:" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." msgstr "" -"ソースコード配布物のメタデータ中に見つかった場合には、以下の規則を適用します:" +"もし該当するならば、 ``#!python`` から始まるスクリプト群が適切なインタープリ" +"タを指し示すように更新します。" -#: ../source/specifications/core-metadata.rst:118 -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 " -"field is not in the sdist, and not marked as ``Dynamic``, then it MUST NOT " -"be present in the wheel." +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -"フィールドが ``Dynamic`` と *マークされていない* 場合は、 sdist からビルドさ" -"れたどの wheel であっても、そのフィールドの値が sdist での値と一致しなければ" -"なりません。そのフィールドが sdist には存在せず、かつ、 ``Dynamic`` とマーク" -"されていない場合には、そのようなフィールドは wheel に出現してはなりません。" +"``distribution-1.0.dist-info/RECORD`` をインストール先のディレクトリパスに更" +"新します。" -#: ../source/specifications/core-metadata.rst:122 +#: ../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:53 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)." +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -"フィールドが ``Dynamic`` とマークされている場合、 (ひとつも存在しない場合も含" -"めて) sdist からビルドされた wheel 内のどんな正当な値を取っても構いません。" +"インストールされた .py のファイルを全て .pyc にコンパイルします。 (アンインス" +"トーラは、 RECORD で言及されていなくても .pyc ファイルを削除できるほどに賢く" +"あるべきです。)" -#: ../source/specifications/core-metadata.rst:125 +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "推奨されるインストーラの機能" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "``#!python`` を書き換えます。" + +#: ../source/specifications/binary-distribution-format.rst:60 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)." +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"python'``, rewrite to point to the correct interpreter. Unix installers may " +"need to add the +x bit to these files if the archive was created on Windows." msgstr "" -"sdist のメタデータバージョンがバージョン 2.2 よりも古い場合には、すべての" -"フィールドが ``Dynamic`` であると指定されたかのように (つまり、その sdist か" -"らビルドされた wheel のメタデータに何も特別な制約がないかのように) 取り扱うべ" -"きです。" +"wheel では、スクリプトは ``{distribution}-{version}.data/scripts/`` にパッ" +"ケージされます。 ``scripts/`` ディレクトリにあるファイルの先頭行が正確に " +"``b'#!python'`` で始まっている場合には、正確なインタープリタを指し示すように" +"書き換えられます。アーカイブが Windows で作成されていれば、 Unix でのインス" +"トーラがこのようなファイルに +x ビットを追加設定する必要があるでしょう。" -#: ../source/specifications/core-metadata.rst:129 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" -"In any context other than a source distribution, ``Dynamic`` is for " -"information only, and indicates that the field value was calculated at wheel " -"build time, and may not be the same as the value in the sdist or in other " -"wheels for the project." +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." msgstr "" -"ソースコード配布物を除くすべての文脈で、 ``Dynamic`` は情報提供の目的のみであ" -"り、そのフィールドの値がビルドの際に計算されたものであって、 sdist や同じプロ" -"ジェクトでも他の wheel ファイルでは異なる場合があることを示します。" +"``b'#!pythonw'`` と書く慣習も許容されています。 ``b'#!pythonw'`` というのはコ" +"ンソール版ではなくて GUI 版のスクリプトであることを示します。" -#: ../source/specifications/core-metadata.rst:134 +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "スクリプトラッパを生成します。" + +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" -"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." -msgstr "``Dynamic`` の詳細かつ完全な意味は :pep:`643` に記述されています。" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" +"wheel では、 Unix システム上でパッケージされたスクリプトには .exe ラッパーが" +"随伴していないことが普通でしょう。 Windows インストーラは、インストールする際" +"にそれらを追加したくなるかもしれません。" -#: ../source/specifications/core-metadata.rst:139 -msgid "Platform (multiple use)" -msgstr "Platform (複数回の使用可)" +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "推奨されるアーカイバの機能" -#: ../source/specifications/core-metadata.rst:143 +#: ../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:78 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." +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." msgstr "" -"Platform の仕様は、その配布物がサポートするオペレーティングシステムを記述した" -"もので、 \"Operating System\" Trove 分類子には記載されていないもの。後述の " -"\"分類子 \" を見てください。" +"アーカイバには、 ``.dist-info`` ファイルをアーカイブの物理的な末尾に置くこと" +"が推奨されています。こうすることで、アーカイブ全体を書き換えなくてもメタデー" +"タを修正することができる点を含む、 ZIP のいくつかの潜在的に興味深いトリックを" +"使うことができるようになります。" -#: ../source/specifications/core-metadata.rst:147 -#: ../source/specifications/core-metadata.rst:471 -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:536 -#: ../source/specifications/core-metadata.rst:592 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:755 -#: ../source/specifications/core-metadata.rst:796 -#: ../source/specifications/core-metadata.rst:818 -msgid "Examples::" -msgstr "例::" +#: ../source/specifications/binary-distribution-format.rst:85 +msgid "File Format" +msgstr "ファイルフォーマット" -#: ../source/specifications/core-metadata.rst:155 -msgid "Supported-Platform (multiple use)" -msgstr "Supported-Platform (複数回の使用可)" +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "ファイル名の慣習" -#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/binary-distribution-format.rst:92 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 " -"binary distribution was compiled. The semantics of the Supported-Platform " -"field are not specified in this PEP." +"The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" +"{abi tag}-{platform tag}.whl``." msgstr "" -"PKG-INFO ファイルを含むバイナリ配布物は、内包するメタデータの中の Supported-" -"Platform フィールドを使って当該バイナリ配布物がどの OS や CPU 向けにコンパイ" -"ルされたかを指定することになるでしょう。 Supported-Platform フィールドのセマ" -"ンティクスは PEP には定義されたものがありません。" - -#: ../source/specifications/core-metadata.rst:173 -msgid "Summary" -msgstr "Summary" +"wheel のファイル名は(訳注、慣習として) ``{配布物}-{バージョン}(-{ビルドタ" +"グ})?-{python タグ}-{abi タグ}-{プラットフォームタグ}.whl <{distribution}-" +"{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl>`` です。" -#: ../source/specifications/core-metadata.rst:177 -msgid "A one-line summary of what the distribution does." -msgstr "その配布物が何をするものかを１行で記述した要約。" +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "distribution" +msgstr "配布物" -#: ../source/specifications/core-metadata.rst:197 -msgid "This field may be specified in the message body instead." -msgstr "このフィールドの代わりにメッセージ本体で指定しても構いません。" +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "配布物の名前、例えば 'django' や 'pyramid' 。" -#: ../source/specifications/core-metadata.rst:200 -msgid "" -"A longer description of the distribution that can run to several " -"paragraphs. Software that deals with metadata should not assume any maximum " -"size for this field, though people shouldn't include their instruction " -"manual as the description." +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" msgstr "" -"配布物に関する長めの説明文で、いくつかの段落に渡ってもかまいません。取扱説明" -"書並みの記述をするべきではありませんが、メタデータを扱うソフトウェアはこの" -"フィールドに最大長さがあるものと仮定すべきではありません。" -#: ../source/specifications/core-metadata.rst:205 +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "配布物のバージョン、例えば 1.0 。" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "ビルドタグ" + +#: ../source/specifications/binary-distribution-format.rst:102 msgid "" -"The contents of this field can be written using reStructuredText markup " -"[1]_. For programs that work with the metadata, supporting markup is " -"optional; programs can also display the contents of the field as-is. This " -"means that authors should be conservative in the markup they use." +"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, " +"and other tags). Sort as an empty tuple if unspecified, else sort as a two-" +"item tuple with the first item being the initial digits as an ``int``, and " +"the second item being the remainder of the tag as a ``str``." msgstr "" -"このフィールドの内容は、 reStructuredText マークアップ [1]_ を使って書いても" -"構いません。メタデータを取り扱うプログラムの側ではマークアップをサポートして" -"もしなくてもかまわず、サポートしない場合にはこのフィールドの内容をそのまま表" -"示することも可能です。つまり、作者の側は、自分が採用するマークアップ言語につ" -"いては保守的であるべきだということになります。" +"省略可能なビルドナンバー。数字で始まらなければなりません。ふたつの wheel ファ" +"イルのファイル名がこの部分を除いて (すなわち名称やバージョンやその他のタグ" +"が) 同一であった場合のタイブレーカ (訳注、いずれかに決めるための方法) として" +"働きます。指定されていれば先頭の数字を ``int`` として解釈して第１要素とし残り" +"を ``str`` として解釈して第２要素とするような要素数が２個のタプルとして解釈さ" +"れ、指定されていない場合には空欄のタプルとして解釈されます。" -#: ../source/specifications/core-metadata.rst:211 +#: ../source/specifications/binary-distribution-format.rst:109 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 " -"pipe (\"|\") char. As a result, the Description field is encoded into a " -"folded field that can be interpreted by RFC822 parser [2]_." +"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 "" -"空行および RFC 822 に従う字下げをサポートするために、すべての CRLF 文字には７" -"個の空白文字と１個のパイプ文字 (\"|\") がこの順に並ぶ文字列が後続しなければな" -"りません。その結果として、Description フィールドが RFC 822 構文解析器 [2]_ で" -"解析可能な形の改行可能なフィールドにエンコードされます。" +"ビルド番号に係るよくあるユースケースは、CPython のリリース前のバージョンを" +"使って manylinux で配布物をビルドしている場合のように、ビルド環境に変化があっ" +"たためにバイナリ配布物を再ビルドする時です。" -#: ../source/specifications/core-metadata.rst:228 +#: ../source/specifications/binary-distribution-format.rst:116 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." +"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 "" -"このエンコーディングが意味するところは、その折り畳まれたフィールドをRFC822 読" -"み取り器で読み取る時には、CRLF と７個の空白文字とそれに引き続くパイプ文字が出" -"現するたびにそれを単独の CRLF に置き換えなければならないということです。" +"ビルド番号は、配布物のバージョンの一部ではなく、従って外部からの、特に " +"Python エコシステムのツール類や標準類の外側からの参照は困難です。配布物が外部" +"からの参照を必要とするようなケースとしては、セキュリティ上の脆弱性を解決しよ" +"うとする場合がよくあるケースです。" -#: ../source/specifications/core-metadata.rst:232 +#: ../source/specifications/binary-distribution-format.rst:121 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)." +"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 "" -"代替策として、配布物に関する説明を代わりにメッセージボディに書く (つまり、字" -"下げやその他の特別なフォーマットを使わずに、ヘッダの並びの後の完全な空行に続" -"けて書く) こともできます。" +"この制約のゆえに、外部から参照される必要がある新たな配布物は、新しい配布物を" +"ビルドする際にビルド番号を使う **べきではありません** 。そのような場合には、" +"代わりに **新しい配布物バージョン** が作成されるべきです。" -#: ../source/specifications/core-metadata.rst:241 -msgid "Description-Content-Type" -msgstr "Description-Content-Type" +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "言語の実装とバージョンタグ" -#: ../source/specifications/core-metadata.rst:245 -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/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "例えば、 'py27' ・ 'py2' ・ 'py3' 。" -#: ../source/specifications/core-metadata.rst:248 -msgid "" -"Historically, PyPI supported descriptions in plain text and " -"`reStructuredText (reST) `_, and could render reST into HTML. However, it is " -"common for distribution authors to write the description in `Markdown " -"`_ (:rfc:`7763`) as many code " -"hosting sites render Markdown READMEs, and authors would reuse the file for " -"the description. PyPI didn't recognize the format and so could not render " -"the description correctly. This resulted in many packages on PyPI with " -"poorly-rendered descriptions when Markdown is left as plain text, or worse, " -"was attempted to be rendered as reST. This field allows the distribution " -"author to specify the format of their description, opening up the " -"possibility for PyPI and other tools to be able to render Markdown and other " -"formats." -msgstr "" -"歴史的には PyPI はプレーンテキストおよび `reStructuredText (reST) `_ での " -"description をサポートし、 reST を HTML として表示することができました。しか" -"しながら、多くのソースコード管理サイトが Markdown の README を表示するように" -"なったので、配布物の作者たちが description を `Markdown `_ (:rfc:`7763`) で書くことが普通にな" -"り、作者たちはそのファイルを description として再利用するようになってきまし" -"た。 PyPI はこのフォーマットを認識せず、従って description の内容を正しく表示" -"することができませんでした。その結果、 PyPI 上の多くのパッケージで Markdown " -"がプレーンテキストとして、もっと悪い場合には reST として解釈して、惨めな表示" -"になっていました。このフィールドは配布物の作者がその description のフォーマッ" -"トを指定できるようにしますので、 PyPI やその他のツールが Markdown やその他の" -"フォーマットを正しく表示できるようになる可能性を広げます。" +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "abi タグ" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "例えば、 'cp33m' ・ 'abi3' ・ 'none' 。" + +#: ../source/specifications/binary-distribution-format.rst:133 +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "platform tag" +msgstr "プラットフォームタグ" + +#: ../source/specifications/binary-distribution-format.rst:133 +msgid "E.g. 'linux_x86_64', 'any'." +msgstr "例えば、 'linux_x86_64' ・ 'any' 。" -#: ../source/specifications/core-metadata.rst:261 +#: ../source/specifications/binary-distribution-format.rst:135 msgid "" -"The format of this field is the same as the ``Content-Type`` header in HTTP " -"(i.e.: `RFC 1341 `_). Briefly, this means that it has a ``type/subtype`` part and then " -"it can optionally have a number of parameters:" +"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 " +"Python 2.7 implementation), with no ABI (pure Python), on any CPU " +"architecture." msgstr "" -"このフィールドのフォーマットは HTTP (すなわち `RFC 1341 `_) における ``Content-Type`` ヘッダの" -"それと同じです。端的に言えば、これは ``type/subtype`` の部分を持っていて、オ" -"プションとしていくつかのパラメータを取ることができるというものです:" - -#: ../source/specifications/core-metadata.rst:267 -msgid "Format::" -msgstr "フォーマット::" - -#: ../source/specifications/core-metadata.rst:271 -msgid "The ``type/subtype`` part has only a few legal values:" -msgstr "``type/subtype`` 部分はいくつかの正当な値を取ります:" +"例えば、 ``distribution-1.0.1-py27-none-any.whl`` とは、 'distribution' と呼" +"ばれるパッケージの最初のビルドであって、 Python 2.7 (任意の Python 2.7 実装) " +"で動作し、 ABI を持たず (即ち純 Python) 、任意の CPU アーキテクチャで動作する" +"ということです。" -#: ../source/specifications/core-metadata.rst:273 -msgid "``text/plain``" -msgstr "``text/plain``" +#: ../source/specifications/binary-distribution-format.rst:140 +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 "" +"ファイル名の拡張子を除いて最後の３個の構成要素は、\"互換性タグ\" と呼ばれま" +"す。互換性タグは、インタープリタに対するそのパッケージの基本的な要求事項を表" +"現しており、 PEP 425 に詳しく書かれています。" -#: ../source/specifications/core-metadata.rst:274 -msgid "``text/x-rst``" -msgstr "``text/x-rst``" +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "エスケープとユニコード" -#: ../source/specifications/core-metadata.rst:275 -msgid "``text/markdown``" -msgstr "``text/markdown``" +#: ../source/specifications/binary-distribution-format.rst:147 +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 "" +"ファイル名の構成要素がダッシュ (``-`` つまり HYPHEN-MINUS) で分離されているの" +"で、この文字は構成要素の中に出現してはなりません。これは次のように取り扱われ" +"ます:" -#: ../source/specifications/core-metadata.rst:277 +#: ../source/specifications/binary-distribution-format.rst:150 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 " -"assumed to be ``UTF-8``." +"In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " +"and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " +"characters should be replaced with corresponding lowercase ones. This is " +"equivalent to regular :ref:`name normalization ` " +"followed by replacing ``-`` with ``_``. Tools consuming wheels must be " +"prepared to accept ``.`` (FULL STOP) and uppercase letters, however, as " +"these were allowed by an earlier version of this specification." msgstr "" -"``charset`` パラメータは、description のキャラクターのエンコーディングを指定" -"するために使われます。唯一の正当な値は ``UTF-8`` です。省略時には ``UTF-8`` " -"であるものと仮定します。" +"配布物の名前の部分では、 ``-_.`` (HYPHEN-MINUS ・ LOW LINE ・ FULL STOP) の文" +"字は、すべて ``_`` (LOW LINE) で置き換えられるべきで、かつ、大文字はすべて対" +"応する小文字に置き換えられるべきです。これは、通常の :ref:`名前の正規化 " +"` の後に ``-`` を ``_`` で置き換えるのと同じです。 wheel " +"ファイルを入力とするツールは、 ``.`` (FULL STOP) や大文字を受け入れる準備がで" +"きていなければなりませんが、しかし、それはこの仕様の初期のバージョンで許され" +"ていたからです。" -#: ../source/specifications/core-metadata.rst:281 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" -"Other parameters might be specific to the chosen subtype. For example, for " -"the ``markdown`` subtype, there is an optional ``variant`` parameter that " -"allows specifying the variant of Markdown in use (defaults to ``GFM`` if not " -"specified). Currently, two variants are recognized:" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." msgstr "" -"サブタイプを選択するために他のパラメータが指定される場合もあります。例えば、 " -"``markdown`` サブタイプを指定する際に、使われている Markdown の異種 (指定がな" -"い場合にはデフォルトでは ``GFM``) を指定することができるオプションの " -"``variant`` パラメータが存在します。現時点ではふたつの異種が認識されます:" +"バージョン番号は、 `バージョン指定子仕様 ` に従って正規化" +"されなければなりません。正規化済みのバージョン番号は ``-`` を含んでいてはなり" +"ません。" -#: ../source/specifications/core-metadata.rst:286 -msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" -msgstr "``GFM`` すなわち :rfc:`Github 流の Markdown <7764#section-3.2>`" +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" +"残りの構成要素は、 ``-`` 文字を含んでいてはいけないので、エスケープ処理を行う" +"必要がありません。" -#: ../source/specifications/core-metadata.rst:287 -msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" -msgstr ":rfc:`CommonMark <7764#section-3.5>` を指定する ``CommonMark``" +#: ../source/specifications/binary-distribution-format.rst:162 +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 "" +"wheel ファイルを生成するツールはファイル名部分の構成要素が ``-`` を含んでいな" +"いことを検証しなければなりませんが、これは、もし含んでいれば結果として生成さ" +"れたファイルが正しく処理されないかもしれないからです。" -#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/binary-distribution-format.rst:165 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." +"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 "" -"``Description-Content-Type`` が指定されていない場合には、アプリケーションとし" -"ては、まず ``text/x-rst; charset=UTF-8`` として表示を試み、正当な rst ではな" -"い場合に ``text/plain`` にフォールバックするべきです。" +"アーカイブのファイル名は Unicode です。いくつかのツールでは非 ASCII 文字の" +"ファイル名をサポートするように更新されるまでに幾らかの時間がかかるかもしれま" +"せんが、しかし、この仕様ではサポートされているのです。" -#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/binary-distribution-format.rst:169 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)." +"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 "" -"``Description-Content-Type`` が認識できない値である場合には、内容の型が " -"``text/plain`` であるものと仮定します (とはいえ、認識できない値であれば何で" -"あっても PyPI が拒否することになるでしょう) 。" +"アーカイブの *中にある* ファイルのファイル名は、 UTF-8 でエンコードされていま" +"す。 ZIP クライアントのいくつかは共通して UTF-8 のファイル名を正常に表示しま" +"せんが、このエンコーディングは ZIP の仕様でも Python の ``zipfile`` の仕様で" +"も、共にサポートされています。" -#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "ファイルの内容" + +#: ../source/specifications/binary-distribution-format.rst:177 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``." +"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 "" -"``Description-Content-Type`` が ``text/markdown`` で、 ``variant`` が指定され" -"ない場合や認識できない値が指定された場合には、 ``variant`` が ``GFM`` である" -"ものと仮定されます。" +"{distribution} の部分を例えば ``beaglevote`` のようなパッケージ名で置き換" +"え、 {version} の部分を例えば `1.0.0`` のようなバージョン番号で置き換えた " +"wheel ファイルの内容は次のもので構成されています:" -#: ../source/specifications/core-metadata.rst:317 +#: ../source/specifications/binary-distribution-format.rst:181 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." +"``/``, 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 "" -"上記の最後の例を見ると ``charset`` はデフォルトでは ``UTF-8`` であり、 " -"``variant`` はデフォルトでは ``GFM`` ですので、それ以前の例と同等であるという" -"ことになります。" +"アーカイブのルートディレクトリに当たる ``/`` は、``WHEEL`` で指定されている通" +"り ``purelib`` または ``platlib`` にインストールされるファイルをすべて含んで" +"います。通常は、 ``purelib`` や ``platlib`` はいずれも ``site-packages`` で" +"す。" -#: ../source/specifications/core-metadata.rst:326 -msgid "Keywords" -msgstr "キーワード" +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "``{distribution}-{version}.dist-info/`` はメタデータを含んでいます。" -#: ../source/specifications/core-metadata.rst:330 +#: ../source/specifications/binary-distribution-format.rst:185 msgid "" -"A list of additional keywords, separated by commas, to be used to assist " -"searching for the distribution in a larger catalog." +"``{distribution}-{version}.data/`` contains one subdirectory for each non-" +"empty install scheme key not already covered, where the subdirectory name is " +"an index into a dictionary of install paths (e.g. ``data``, ``scripts``, " +"``headers``, ``purelib``, ``platlib``)." msgstr "" -"より大きなカタログで配布物を検索する助けとなるべく使用される、コンマで区切ら" -"れた追加のキーワードのリスト。" +"``{distribution}-{version}.data/`` は、すでにカバーされているものは別として、" +"サブディレクトリ名がインストールパスの辞書への (例えば、 ``data``, " +"``scripts``, ``headers``, ``purelib``, ``platlib`` のような) 指示子になってい" +"るような、空ではないそれぞれのインストールスキームに対応したディレクトリを含" +"みます。" -#: ../source/specifications/core-metadata.rst:339 +#: ../source/specifications/binary-distribution-format.rst:189 msgid "" -"The specification previously showed keywords separated by spaces, but " -"distutils and setuptools implemented it with commas. These tools have been " -"very widely used for many years, so it was easier to update the " -"specification to match the de facto standard." +"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 "" -"以前にお見せした仕様ではキーワードを区切るのに空白文字を使っていましたが、 " -"distutils と setuptools はコンマで区切ります。これらのツールは多年に渡って非" -"常に広く使われていますので、仕様をデファクト標準に合わせる形で更新する方が簡" -"単でした。" +"Python スクリプトは ``scripts`` ディレクトリに置かなければならず、また、イン" +"ストール時のスクリプトラッパの生成や ``#!python`` 書き換えといった利点を活用" +"するために、正確に ``b'#!python'`` で始まっていなければなりません。" -#: ../source/specifications/core-metadata.rst:348 -msgid "Home-page" -msgstr "Home-page" +#: ../source/specifications/binary-distribution-format.rst:193 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" +"``{distribution}-{version}.dist-info/METADATA`` は、バージョン 1.1 またはそれ" +"以上のフォーマットのメタデータです。" -#: ../source/specifications/core-metadata.rst:352 -msgid "A string containing the URL for the distribution's home page." -msgstr "配布物のホームページを示す URL を含んだ文字列。" +#: ../source/specifications/binary-distribution-format.rst:195 +msgid "" +"``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " +"itself in the same basic key: value format::" +msgstr "" +"``{distribution}-{version}.dist-info/WHEEL`` は、同様のキー:バリュー形式で表" +"現されたアーカイブそのものに関するメタデータです::" -#: ../source/specifications/core-metadata.rst:361 -msgid "Download-URL" -msgstr "Download-URL" +#: ../source/specifications/binary-distribution-format.rst:205 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "``Wheel-Version`` は、Wheel の仕様のバージョン番号です。" -#: ../source/specifications/core-metadata.rst:365 +#: ../source/specifications/binary-distribution-format.rst:206 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\".)" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." msgstr "" -"そこからこのバージョンの配布物をダウンロードすることができる URL を含んだ文字" -"列。 (これが意味するところは、 URL は何か \".../BeagleVote-latest.tgz\" のよ" -"うなものでは駄目で、 \".../BeagleVote-0.45.tgz\" のようにバージョンを含むもの" -"でなければならないということです。)" - -#: ../source/specifications/core-metadata.rst:374 -msgid "Author" -msgstr "Author" +"``Generator`` は、そのアーカイブを作成したソフトウェアの名前で、バージョン番" +"号を付加しても構いません。" -#: ../source/specifications/core-metadata.rst:378 +#: ../source/specifications/binary-distribution-format.rst:208 msgid "" -"A string containing the author's name at a minimum; additional contact " -"information may be provided." +"``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/core-metadata.rst:391 -msgid "Author-email" -msgstr "Author-email" +"``Root-Is-Purelib`` は、アーカイブの最上位のディレクトリが pure lib へインス" +"トールされるべきものであれば true で、そうでなければ platlib へインストールさ" +"れます。" -#: ../source/specifications/core-metadata.rst:395 +#: ../source/specifications/binary-distribution-format.rst:211 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." +"``Tag`` is the wheel's expanded compatibility tags; in the example the " +"filename would contain ``py2.py3-none-any``." msgstr "" -"作者の電子メールアドレスを含む文字列。 RFC-822 の ``From:`` ヘッダの記述形式" -"として正当な形で名前と電子メールアドレスを含んでいても構いません。" +"``Tag`` は、 wheel の拡張互換性タグで、例の中ではファイル名の ``py2.py3-none-" +"any`` の部分です。" -#: ../source/specifications/core-metadata.rst:403 -#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/binary-distribution-format.rst:213 msgid "" -"Per RFC-822, this field may contain multiple comma-separated e-mail " -"addresses::" +"``Build`` is the build number and is omitted if there is no build number." msgstr "" -"RFC-822 によれば、このフィールドは、複数の電子メールアドレスをコンマで区切っ" -"て記述しても構いません::" - -#: ../source/specifications/core-metadata.rst:413 -msgid "Maintainer" -msgstr "メンテナ" +"``Build`` は、ビルドナンバーで、もしビルドナンバーがなければ省略されます。" -#: ../source/specifications/core-metadata.rst:417 +#: ../source/specifications/binary-distribution-format.rst:214 msgid "" -"A string containing the maintainer's name at a minimum; additional contact " -"information may be provided." +"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 "" -"少なくともメンテナの名前を含む文字列で、連絡先となる情報を追加しても構いませ" -"ん。" +"wheel インストーラは、もし自身がサポートしているものより Wheel-Version が大き" +"ければ警告するべきですし、 Wheel-Version のメジャーバージョンがサポートしてい" +"るものより大きい場合にはフェイルするべきです。" -#: ../source/specifications/core-metadata.rst:420 +#: ../source/specifications/binary-distribution-format.rst:217 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``." +"Wheel, being an installation format that is intended to work across multiple " +"versions of Python, does not generally include .pyc files." msgstr "" -"当該プロジェクトが元々の作者とは異なる誰かによって保守されている場合にこの" -"フィールドを使うことを想定しているということを覚えておいてください: もし " -"``Author`` と同一人物であれば、このフィールドを省略するべきです。" +"Wheel は複数のバージョンの Python を跨いでも動作するように意図されたインス" +"トール用のフォーマットですが、通常は .pyc ファイルを含みません。" -#: ../source/specifications/core-metadata.rst:434 -msgid "Maintainer-email" -msgstr "Maintainer-email" +#: ../source/specifications/binary-distribution-format.rst:219 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "Wheel は、 setup.py ないし setup.cfg を含みません。" -#: ../source/specifications/core-metadata.rst:438 +#: ../source/specifications/binary-distribution-format.rst:221 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." +"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 " +"layout offers a superset of the functionality provided by the existing " +"wininst and egg binary formats." msgstr "" -"メンテナの電子メールアドレスを含む文字列。 RFC-822 の ``From:`` ヘッダの記述" -"形式として正当な形で名前と電子メールアドレスを含んでいても構いません。" +"このバージョンの wheel 仕様は、distutils のインストール方法論に基づいていて、" +"ファイルを他の場所にインストールする方法については定義していません。既存の " +"wininst や egg バイナリフォーマットが提供する機能の上位互換のレイアウトを提案" +"します。" -#: ../source/specifications/core-metadata.rst:442 +#: ../source/specifications/binary-distribution-format.rst:228 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr ".dist-info ディレクトリ" + +#: ../source/specifications/binary-distribution-format.rst:230 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``." +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." msgstr "" -"当該プロジェクトが元々の作者とは異なる誰かによって保守されている場合にこの" -"フィールドを使うことを想定しているということを覚えておいてください: もし " -"``Author-email`` と同一であれば、このフィールドを省略するべきです。" - -#: ../source/specifications/core-metadata.rst:460 -msgid "License" -msgstr "License" +"Wheel の .dist-info ディレクトリは、最低限でも METADATA ・ WHEEL ・RECORD を" +"含みます。" -#: ../source/specifications/core-metadata.rst:464 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "" -"Text indicating the license covering the distribution where the license is " -"not a selection from the \"License\" Trove classifiers. See :ref:" -"`\"Classifier\" ` below. This field may also be used to " -"specify a particular version of a license which is named via the " -"``Classifier`` field, or to indicate a variation or exception to such a " -"license." +"METADATA is the package metadata, the same format as PKG-INFO as found at " +"the root of sdists." msgstr "" -"\"License\" Trove 分類子から選択したものではないライセンスの場合は、配布物を" -"カバーするライセンスを示すテキスト。後述の :ref:`\"Classifier\" ` を見てください。このフィールドは、 ``Classifier`` フィールドを経" -"由して名指しされたライセンスの特定のバージョンを指定したり、そのようなライセ" -"ンスに対する変種や例外事項を示したりするのに使っても構いません。" +"METADATA はパッケージのメタデータで、 sdists のルートディレクトリにある PKG-" +"INFO と同じフォーマットで記述されます。" -#: ../source/specifications/core-metadata.rst:484 -msgid "Classifier (multiple use)" -msgstr "Classifier (複数回の使用可)" +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" +"WHEEL は、パッケージをビルドする部分に特化した wheel のメタデータです。" -#: ../source/specifications/core-metadata.rst:488 +#: ../source/specifications/binary-distribution-format.rst:235 msgid "" -"Each entry is a string giving a single classification value for the " -"distribution. Classifiers are described in :pep:`301`, and the Python " -"Package Index publishes a dynamic list of `currently defined classifiers " -"`__." +"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 " +"hash of itself, must include its hash. The hash algorithm must be sha256 or " +"better; specifically, md5 and sha1 are not permitted, as signed wheel files " +"rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -"それぞれのエントリは、当該配布物を分類する値をひとつ与える文字列です。分類子" -"については :pep:`301` に記述されていて、The Python Package Index は `現在定義" -"されている分類子 `__ という動的なリストを公開" -"しています。" - -#: ../source/specifications/core-metadata.rst:493 -#: ../source/specifications/core-metadata.rst:583 -#: ../source/specifications/core-metadata.rst:723 -#: ../source/specifications/core-metadata.rst:748 -msgid "This field may be followed by an environment marker after a semicolon." -msgstr "このフィールドでは、セミコロンの後に環境指標を続けても構いません。" +"RECORD は、 wheel に含まれる (ほとんど) 全てのファイルとそのセキュアなハッ" +"シュ値のリストです。 PEP 376 とは異なり、自分自身のハッシュ値を内包することは" +"不可能な RECORD を除く各ファイルのハッシュ値が含まれていなければなりません。" +"署名済みの wheel ファイルがアーカイブの完全性を検証するのに RECORD 内の暗号学" +"的に強いハッシュ値に依存しているので、ハッシュ計算のアルゴリズムは sha256 以" +"上でなければならず、特に md5 とsha1 は許されません。" -#: ../source/specifications/core-metadata.rst:504 -msgid "Requires-Dist (multiple use)" -msgstr "Requires-Dist (複数回の使用可)" +#: ../source/specifications/binary-distribution-format.rst:241 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "PEP 376 の INSTALLER と REQUESTED はアーカイブに含まれません。" -#: ../source/specifications/core-metadata.rst:507 -#: ../source/specifications/core-metadata.rst:570 -#: ../source/specifications/core-metadata.rst:695 -#: ../source/specifications/core-metadata.rst:737 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" -"The field format specification was relaxed to accept the syntax used by " -"popular publishing tools." +"RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -"フィールドの仕様は、人気のある公開ツール群が用いる構文を許容するように緩めら" -"れました。" +"RECORD.jws は、デジタル署名のために使われます。これについては RECORD では触れ" +"られません。" -#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/binary-distribution-format.rst:244 msgid "" -"Each entry contains a string naming some other distutils project required by " -"this distribution." +"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 "" -"それぞれのエントリは、この配布物が要求する他の distutils のプロジェクトを名指" -"しする文字列を含みます。" - -#: ../source/specifications/core-metadata.rst:514 -msgid "The format of a requirement string contains from one to four parts:" -msgstr "要求事項を示す文字列のフォーマットは、１個から４個の部分を含みます:" +"自分の wheel ファイルを S/MIME 署名でセキュアにすることを好む人は、 RECORD." +"p7s を使うことができます。これについては RECORD では触れられません。" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/binary-distribution-format.rst:247 msgid "" -"A project name, in the same format as the ``Name:`` field. The only " -"mandatory part." +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD and its signatures, installation will " +"fail if any file in the archive is not both mentioned and correctly hashed " +"in RECORD." msgstr "" -"``Name:`` フィールドと同じフォーマットのプロジェクト名。これだけが必須部分で" -"す。" +"展開中に wheel インストーラは RECORD 内のハッシュ値と実際のファイルの内容 (の" +"ハッシュ値) をすべて検証します。 RECORD とその署名による検証に加えて、アーカ" +"イブの中のいずれかのファイルが RECORD にリストされていないか、または、正しく" +"ハッシュされていない時にはインストールがフェイルするでしょう。" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/binary-distribution-format.rst:254 +msgid "The .data directory" +msgstr ".data ディレクトリ" + +#: ../source/specifications/binary-distribution-format.rst:256 msgid "" -"A comma-separated list of 'extra' names. These are defined by the required " -"project, referring to specific features which may need extra dependencies. " -"The names MUST conform to the restrictions specified by the ``Provides-Extra:" -"`` field." +"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 "" -"コンマ区切りの '追加の' 名前のリスト。これらは、追加的な依存先を必要とする特" -"定の機能に応じて、要求されたプロジェクトによって定義されます。この名前は、 " -"``Provides-Extra:`` フィールドで指定された制約事項に従うものでなければなりま" -"せん。" +"site-packages 内に通常通りにインストールされなかったファイルはどれでも、." +"dist-info ディレクトリと同様に命名されるが .data/ 拡張子をつけられて .data " +"ディレクトリに行きます::" -#: ../source/specifications/core-metadata.rst:522 +#: ../source/specifications/binary-distribution-format.rst:264 msgid "" -"A version specifier. Tools parsing the format should accept optional " -"parentheses around this, but tools generating it should not use parentheses." +"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 "" -"バージョン指定子。この部分をパースするツールはバージョンを囲む括弧を許容しな" -"ければならないが、生成する際には括弧を使ってはなりません。" +".data ディレクトリでは、配布物からのスクリプト・ヘッダー・説明文書などをサブ" +"ディレクトリに収めています。インストール中に、これらのサブディレクトリの内容" +"を行き先となるパスへ動かします。" -#: ../source/specifications/core-metadata.rst:525 +#: ../source/specifications/binary-distribution-format.rst:270 +msgid "Signed wheel files" +msgstr "署名済み wheel ファイル" + +#: ../source/specifications/binary-distribution-format.rst:272 msgid "" -"An environment marker after a semicolon. This means that the requirement is " -"only needed in the specified conditions." +"Wheel files include an extended RECORD that enables digital signatures. PEP " +"376's RECORD is altered to include a secure hash " +"``digestname=urlsafe_b64encode_nopad(digest)`` (urlsafe base64 encoding with " +"no trailing = characters) as the second column instead of an md5sum. All " +"possible entries are hashed, including any generated files such as .pyc " +"files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -"セミコロンの後ろに環境マーカ。要求事項が必要となるのが指定された条件の時のみ" -"であることを示します。" - -#: ../source/specifications/core-metadata.rst:528 -msgid "See :pep:`508` for full details of the allowed format." -msgstr "許容されるフォーマットの詳細については :pep:`508` を見てください。" +"Wheel ファイルは、デジタル署名を可能にした拡張 RECORD ファイルを含みます。 " +"PEP 376 の RECORD は、 md5sum の代わりにセキュアなハッシュ値 " +"``digestname=urlsafe_b64encode_nopad(digest)`` (末尾に = 文字を追加しない " +"url セーフな base64 エンコード) を二つ目のカラムとするように修正されました。" +"生成された .pyc ファイルなども含むすべての可能なエントリにハッシュ値が付加さ" +"れていますが、 RECORD は自身のハッシュ値を含むことができないので例外です。例" +"えば::" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/binary-distribution-format.rst:283 msgid "" -"The project names should correspond to names as found on the `Python Package " -"Index`_." +"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 " +"file in the archive must have a correct hash in RECORD or the installation " +"will fail." msgstr "" -"プロジェクト名は、 `Python パッケージインデックス `_ に" -"出現する名前に対応していなければなりません。" +"署名用のファイルである RECORD.jws と RECORD.p7s は、 RECORD ファイルが作成さ" +"れた後にしか追加できないので、RECORD ファイル内で言及されることは全くありませ" +"ん。アーカイブの中の他のファイルはすべて、RECORD ファイル内に正しいハッシュ値" +"を持たなければならず、そうでなければインストールに失敗します。" -#: ../source/specifications/core-metadata.rst:533 +#: ../source/specifications/binary-distribution-format.rst:288 msgid "" -"Version specifiers must follow the rules described in :doc:`version-" -"specifiers`." +"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:" msgstr "" -"バージョン指定子は :doc:`version-specifiers` に記述された規則に従っていなけれ" -"ばなりません。" +"JSON ウェブ署名が使われる場合には、ひとつかそれ以上の JSON Web Signature " +"JSON Serialization (JWS-JS) 署名が RECORD ファイルの隣にある RECORD.jws ファ" +"イルの中に保存されます。 RECORD ファイルの SHA-256 ハッシュ値を署名の JSON ペ" +"イロードに含むことで RECORD ファイルに署名するために JWS が使われます:" -#: ../source/specifications/core-metadata.rst:547 -msgid "Requires-Python" -msgstr "" +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "(The hash value is the same format used in RECORD.)" +msgstr "(ハッシュ値の書き方のフォーマットは RECORD で使われるものと同じです。)" -#: ../source/specifications/core-metadata.rst:551 +#: ../source/specifications/binary-distribution-format.rst:299 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 "" -"このフィールドは、配布物が互換性を持つ Python のバージョン (複数可) を指定し" -"ます。インストールツールは、プロジェクトのインストールするべきバージョンを選" -"択する時にこのフィールドを参照しても構いません。" - -#: ../source/specifications/core-metadata.rst:555 -msgid "The value must be in the format specified in :doc:`version-specifiers`." +"If RECORD.p7s is used, it must contain a detached S/MIME format signature of " +"RECORD." msgstr "" -"値は、 :doc:`version-specifiers` で指定されたフォーマットでなければなりませ" -"ん。" +"RECORD.p7s を使う場合は、このファイルに RECORD ファイルに関する分離型の S/" +"MIME 署名を入れておかなければなりません。" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/binary-distribution-format.rst:302 msgid "" -"For example, if a distribution uses :ref:`f-strings ` " -"then it may prevent installation on Python < 3.6 by specifying::" +"A wheel installer is not required to understand digital signatures but MUST " +"verify the hashes in RECORD against the extracted file contents. When the " +"installer checks file hashes against RECORD, a separate signature checker " +"only needs to establish that RECORD matches the signature." msgstr "" -"例えば、ある配布物が :ref:`f-strings ` を使っているなら、" -"次のように指定することで Python < 3.6 上にインストールするのを抑止してもかま" -"いません::" +"wheel インストーラはデジタル署名を理解することを要求されてはいませんが、 " +"RECORD ファイル内のハッシュ値が展開されたファイル内容に対して妥当であることを" +"検証しなければなりません。インストーラが RECORD ファイルに対するハッシュ値を" +"確認する際には、別途用意された署名検証プログラムは RECORD ファイルが署名に対" +"して妥当であることだけを確認すれば十分です。" -#: ../source/specifications/core-metadata.rst:562 -msgid "This field cannot be followed by an environment marker." -msgstr "このフィールドでは、環境マーカを後ろに付けることはできません。" +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "See" +msgstr "以下を参照のこと" -#: ../source/specifications/core-metadata.rst:567 -msgid "Requires-External (multiple use)" -msgstr "Requires-External (複数回の使用可)" +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "https://datatracker.ietf.org/doc/html/rfc7515" +msgstr "https://datatracker.ietf.org/doc/html/rfc7515" -#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/binary-distribution-format.rst:310 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 " -"to downstream project maintainers, and has no semantics which are meaningful " -"to the ``distutils`` distribution." +"https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +"serialization-01" msgstr "" -"それぞれのエントリは、その配布物が使われるシステムにおける何らかの依存関係を" -"記述する文字列です。このフィールドは、ダウンストリームプロジェクトの維持管理" -"担当者向けにヒントを提供することを意図しており、 ``distutils`` 配布物にとって" -"は何ら意味を持ちません。" +"https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +"serialization-01" -#: ../source/specifications/core-metadata.rst:579 -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/binary-distribution-format.rst:311 +msgid "https://datatracker.ietf.org/doc/html/rfc7517" +msgstr "https://datatracker.ietf.org/doc/html/rfc7517" -#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/binary-distribution-format.rst:312 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:" -"`Version specifier specification `: they should " -"correspond to the version scheme used by the external dependency." +"https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -"それらは非 Python のソフトウェアリリースを参照するものですので、このフィール" -"ドでのバージョン番号は :ref:`バージョン指定子仕様 ` で指" -"定されたフォーマットに適合することを **要求されていません** : それらは、外部" -"依存関係によって使われるバージョンスキームに対応するべきです。" +"https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" -#: ../source/specifications/core-metadata.rst:590 -msgid "Notice that there is no particular rule on the strings to be used." -msgstr "使用される文字列に対して特に規則がないという点に注意してください。" +#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/platform-compatibility-tags.rst:268 +msgid "FAQ" +msgstr "FAQ" -#: ../source/specifications/core-metadata.rst:602 -msgid "Project-URL (multiple-use)" -msgstr "Project-URL (複数回の使用可)" +#: ../source/specifications/binary-distribution-format.rst:320 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" +"Wheel は .data ディレクトリを定義します。すべてのデータをそこに入れるべきで" +"しょうか？" -#: ../source/specifications/core-metadata.rst:606 +#: ../source/specifications/binary-distribution-format.rst:322 msgid "" -"A string containing a browsable URL for the project and a label for it, " -"separated by a comma." +"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 "" -"そのプロジェクトの閲覧可能な URL とラベルを含む文字列をコンマで区切ったもの。" - -#: ../source/specifications/core-metadata.rst:613 -msgid "The label is free text limited to 32 characters." -msgstr "このラベルは32 文字以内のフリーテキストです。" +"この仕様では、あなたがあなたのソースコードをどのように組織立てて置くべきかに" +"ついては特に意見を表明していません。 .data ディレクトリは、 ``site-" +"packages`` 内や PYTHONPATH 内に通常ならインストールされない全てのファイルを置" +"く場所というだけのことです。換言すれば、 *そのような* ファイル群が通常なら " +"*wheel の* ``.data`` ディレクトリに置く形で配布されない時でさえも、 " +"``pkgutil.get_data(package, resource)`` を使い続けても構わないのです。" -#: ../source/specifications/core-metadata.rst:621 -msgid "Provides-Extra (multiple use)" -msgstr "Provides-Extra (複数回の使用可)" +#: ../source/specifications/binary-distribution-format.rst:331 +msgid "Why does wheel include attached signatures?" +msgstr "なぜ wheel は添付された署名を持つのか？" -#: ../source/specifications/core-metadata.rst:624 +#: ../source/specifications/binary-distribution-format.rst:333 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." +"Attached signatures are more convenient than detached signatures because " +"they travel with the archive. Since only the individual files are signed, " +"the archive can be recompressed without invalidating the signature or " +"individual files can be verified without having to download the whole " +"archive." msgstr "" -"曖昧さ (すなわち正規化が要求されていない) を避けるために :pep:`685` で制限さ" -"れた正当な値を。古めのメタデータのバージョンでは、 ``Name:`` を伴う行で値に制" -"限が導入され、正規化規則も導入されました。" +"添付された署名は、アーカイブと一体のものとして転送されるので、分離署名よりも" +"便利です。個々のファイルが署名されているだけなので、アーカイブを圧縮し直して" +"も署名が無効にならず、また、アーカイブ全体をダウンロードしなくても個々のファ" +"イルの検証を行うことができます。" -#: ../source/specifications/core-metadata.rst:629 -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 " -"and end with a letter or number. Hyphens cannot be followed by another " -"hyphen. Names are limited to those which match the following regex (which " -"guarantees unambiguity)::" -msgstr "" -"追加的な機能の名前を含む文字列。正当な名前は、 ASCII 小文字・ ASCII 数字・ハ" -"イフンからのみ構成されます。先頭と末尾は文字か数字でなければなりません。ハイ" -"フンは連続してはいけません。名前は次の正規表現にマッチしなければなりません " -"(そうすることで曖昧さを排除します)::" +#: ../source/specifications/binary-distribution-format.rst:341 +msgid "Why does wheel allow JWS signatures?" +msgstr "なぜ wheel は JWS 署名を許容するのか？" -#: ../source/specifications/core-metadata.rst:637 +#: ../source/specifications/binary-distribution-format.rst:343 msgid "" -"The specified name may be used to make a dependency conditional on whether " -"the optional feature has been requested." +"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 "" -"指定された名前は、追加的な機能が要求されたか否かに応じて依存関係を構築するた" -"めに使われます。" +"JWS がその一部を構成する JOSE の仕様は実装を容易にするように設計されており、" +"その性質は wheel の基本的な設計目標のひとつでもあります。 JWS は使いやすくて" +"簡潔な純 Python の実装をもたらします。" -#: ../source/specifications/core-metadata.rst:645 -msgid "" -"A second distribution requires an optional dependency by placing it inside " -"square brackets, and can request multiple features by separating them with a " -"comma (,). The requirements are evaluated for each requested feature and " -"added to the set of requirements for the distribution." -msgstr "" -"２番目の配布物は、角括弧の中に書くことで追加の依存先を要求し、コンマ (,) で区" -"切ることで複数の機能を要求することができます。要求事項は、要求されたそれぞれ" -"の機能について評価され、配布物の要求する依存関係の組に追加されます。" +#: ../source/specifications/binary-distribution-format.rst:349 +msgid "Why does wheel also allow S/MIME signatures?" +msgstr "なぜ wheel は S/MIME 署名をも許容するのか？" -#: ../source/specifications/core-metadata.rst:655 +#: ../source/specifications/binary-distribution-format.rst:351 msgid "" -"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " -"that are needed for running automated tests and generating documentation, " -"respectively." +"S/MIME signatures are allowed for users who need or want to use existing " +"public key infrastructure with wheel." msgstr "" -"``test`` と ``doc`` という二つの名前は、順に自動化されたテストと説明文書の生" -"成のために必要な依存先として予約されています。" +"S/MIME 署名は、既存の公開鍵基盤を wheel でも採用する必要があるか、または、採" +"用したいユーザのために許容されています。" -#: ../source/specifications/core-metadata.rst:659 +#: ../source/specifications/binary-distribution-format.rst:354 msgid "" -"It is legal to specify ``Provides-Extra:`` without referencing it in any " -"``Requires-Dist:``." +"Signed packages are only a basic building block in a secure package update " +"system. Wheel only provides the building block." msgstr "" -"``Requires-Diet:`` のどこからも参照されていなくても、 ``Provides-Extra:`` を" -"指定しても構いません。" +"署名されたパッケージは、セキュアなパッケージ更新システムを構成するひとつのビ" +"ルディングブロックであるというだけのものです。 Wheel としては、単にビルディン" +"グブロックを提供するだけです。" -#: ../source/specifications/core-metadata.rst:662 -msgid "" -"When writing data for older metadata versions, names MUST be normalized " -"following the same rules used for the ``Name:`` field when performing " -"comparisons. Tools writing metadata MUST raise an error if two ``Provides-" -"Extra:`` entries would clash after being normalized." -msgstr "" -"古めのメタデータのバージョンでデータを書く時、比較を行う時には ``Name:`` " -"フィールドに使われるのと同じ規則に従って正規化されなければなりません。ふたつ" -"の ``Provides-Extra:`` エントリが正規化後に衝突する場合には、メタデータを書き" -"込むツールはエラーを発生させなければなりません。" +#: ../source/specifications/binary-distribution-format.rst:359 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "\"pure lib\" と \"plat lib\" って、どう扱えばいいの？" -#: ../source/specifications/core-metadata.rst:667 +#: ../source/specifications/binary-distribution-format.rst:361 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 " -"would be invalid following the rules for ``Name:`` in any core metadata " -"version, the user SHOULD be warned and the value ignored to avoid ambiguity. " -"Tools MAY choose to raise an error when reading an invalid name for older " -"metadata versions." +"Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " +"significant on some platforms. For example, Fedora installs pure Python " +"packages to '/usr/lib/pythonX.Y/site-packages' and platform dependent " +"packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -"メタデータの古めのバージョンから読み込む時、このフィールドの値が新しめのメタ" -"データバージョンとして正当でない場合にツールが警告するべきです。コアとなるメ" -"タデータのバージョンで ``Name:`` に対する規則に照らして値が正当ではないとすれ" -"ばユーザは警告されるべきで、その値は曖昧さを避けるために無視されるべきです。" -"古めのメタデータバージョンとして不当な名前を読み取った場合には、ツールはエ" -"ラーを発出することを選択しても構いません。" - -#: ../source/specifications/core-metadata.rst:675 -msgid "Rarely Used Fields" -msgstr "稀に使われるフィールド" +"Wheel は \"purelib\" と \"platlib\" を区別して扱いますが、これらはプラット" +"フォームによっては大きな違いがあります。例えば、 Fedora では純 Python のパッ" +"ケージを '/usr/lib/pythonX.Y/site-packages' にインストールし、プラットフォー" +"ムに依存しないパッケージを '/usr/lib64/pythonX.Y/site-packages' にインストー" +"ルします。" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/binary-distribution-format.rst:366 msgid "" -"The fields in this section are currently rarely used, as their design was " -"inspired by comparable mechanisms in Linux package management systems, and " -"it isn't at all clear how tools should interpret them in the context of an " -"open index server such as `PyPI `__." +"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: " +"true\" with those same files in the root, and it is legal to have files in " +"both the \"purelib\" and \"platlib\" categories." msgstr "" -"この節のフィールドは、 Linux のパッケージ管理システムにおける類似の機構に触発" -"されて設計されましたが、 `PyPI `__ のような開放的なインデッ" -"クスサーバの文脈でツールがどのように翻案するべきかが全く明らかではないので、" -"現在ではほとんど使われません。" +"``{name}-{version}.data/purelib`` 内の全てのファイルについて \"Root-Is-" +"Purelib: false\" という設定になっている wheel ファイルは、同じファイルがルー" +"トディレクトリ内にあって \"Root-Is-Purelib: true\" になっている wheel ファイ" +"ルと相同であり、 \"purelib\" と \"platlib\" の両カテゴリにファイル群が存在す" +"ることには問題がありません。" -#: ../source/specifications/core-metadata.rst:682 +#: ../source/specifications/binary-distribution-format.rst:371 msgid "" -"As a result, popular installation tools ignore them completely, which in " -"turn means there is little incentive for package publishers to set them " -"appropriately. However, they're retained in the metadata specification, as " -"they're still potentially useful for informational purposes, and can also be " -"used for their originally intended purpose in combination with a curated " -"package repository." +"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 "" -"その結果として、人気のあるインストールツールでは完全に無視されていて、そのた" -"めに今度はパッケージを公開する側でもこれらのフィールドを適切に設定しておく誘" -"因がほとんどなくなっています。しかしながら、これらのフィールドは、情報提供の" -"目的ではまだ潜在的に役に立つことと、細かく注釈をつけるようなパッケージリポジ" -"トリと組み合わせれば本来意図された目的に用いることができることから、メタデー" -"タの仕様には残されています。" +"実際のところ、 wheel は、それが純 Python なのかそうでないのかによって " +"\"purelib\" または \"platlib\" のいずれか一方しか持たず、 \"Root-Is-" +"purelib\" を適切に設定しつつファイル群をルートディレクトリに置くべきです。" -#: ../source/specifications/core-metadata.rst:692 -msgid "Provides-Dist (multiple use)" -msgstr "Provides-Dist (複数回の使用可)" +#: ../source/specifications/binary-distribution-format.rst:379 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" +"Python のソースコードを wheel ファイルから直接にインポートすることはできます" +"か？" -#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/binary-distribution-format.rst:381 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)." +"Technically, due to the combination of supporting installation via simple " +"extraction and using an archive format that is compatible with " +"``zipimport``, a subset of wheel files *do* support being placed directly on " +"``sys.path``. However, while this behaviour is a natural consequence of the " +"format design, actually relying on it is generally discouraged." msgstr "" -"それぞれのエントリは、この配布物に含まれている Distutils プロジェクトの名前を" -"文字列で含みます。このフィールドは、プロジェクトを特定する ``Name`` フィール" -"ドと後続するバージョンを *含んでいなければなりません*: Name (Version) 。" +"技術的な話としては、単純に展開するだけでインストールできる機能と " +"``zipimport`` と互換性のあるアーカイブフォーマットの両方をサポートしているの" +"で、一部の wheel ファイルは ``sys.path`` に直接に置くことを *サポートしていま" +"す* 。しかし、このような動作はフォーマット設計の自然な結果とはいうものの、実" +"際にはこれに依存することは一般的には推奨されていません。" -#: ../source/specifications/core-metadata.rst:704 +#: ../source/specifications/binary-distribution-format.rst:387 msgid "" -"A distribution may provide additional names, e.g. to indicate that multiple " -"projects have been bundled together. For instance, source distributions of " -"the ``ZODB`` project have historically included the ``transaction`` project, " -"which is now available as a separate distribution. Installing such a source " -"distribution satisfies requirements for both ``ZODB`` and ``transaction``." +"Firstly, wheel *is* designed primarily as a distribution format, so skipping " +"the installation step also means deliberately avoiding any reliance on " +"features that assume full installation (such as being able to use standard " +"tools like ``pip`` and ``virtualenv`` to capture and manage dependencies in " +"a way that can be properly tracked for auditing and security update " +"purposes, or integrating fully with the standard build machinery for C " +"extensions by publishing header files in the appropriate place)." msgstr "" -"配布物は、複数のプロジェクトが一緒に束ねられている場合には、それを示す追加の" -"名前を持っていても構いません。例えば、 ``ZODB`` プロジェクトのソースコード配" -"布物は、歴史的に ``transaction`` プロジェクトを包含していましたが、今では個別" -"の配布物として利用可能です。そのようなソースコード配布物をインストールする" -"と、 ``ZODB`` と ``transaction`` の両方の要求事項を満たします。" +"第一に、wheel は一義的に配布物のフォーマットとして *設計されている* ので、イ" +"ンストールの段階を省略するということは、完全なインストールがなされているもの" +"と仮定している機能 (例えば、正当性監査やセキュリティアップデートのために正し" +"く追跡することができるひとつの方法であるところの ``pip`` や ``virtualenv`` の" +"ような標準ツールを使った依存関係の捕捉や管理の機能、あるいは、ヘッダファイル" +"を適切な場所に公開することによって C 言語拡張をビルドする標準的な機構を完全に" +"統合する機能) への信頼を故意に避けることになります。" -#: ../source/specifications/core-metadata.rst:711 +#: ../source/specifications/binary-distribution-format.rst:396 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 " -"to indicate an abstract capability which could be supplied by one of " -"multiple projects. E.g., multiple projects might supply RDBMS bindings for " -"use by a given ORM: each project might declare that it provides ``ORM-" -"bindings``, allowing other projects to depend only on having at most one of " -"them installed." +"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 " +"has been fully installed. When that assumption is broken by trying to run " +"the software from a zip archive, the failures can often be obscure and hard " +"to diagnose (especially when they occur in third party libraries). The two " +"most common sources of problems with this are the fact that importing C " +"extensions from a zip archive is *not* supported by CPython (since doing so " +"is not supported directly by the dynamic loading machinery on any platform) " +"and that when running from a zip archive the ``__file__`` attribute no " +"longer refers to an ordinary filesystem path, but to a combination path that " +"includes both the location of the zip archive on the filesystem and the " +"relative path to the module inside the archive. Even when software correctly " +"uses the abstract resource APIs internally, interfacing with external " +"components may still require the availability of an actual on-disk file." msgstr "" -"配布物は、また、個別に配布されているどんなプロジェクトにも紐付かない \"仮想の" -"\" プロジェクト名を持っていても構いません: そのような名前は、複数のプロジェク" -"トのうちのひとつで供給される抽象的な能力を示すために使われるかもしれません。" -"例えば、複数のプロジェクトがとある ORM で使われる RDBMS バインディングを提供" -"していても構いません: それぞれのプロジェクトが、他のプロジェクトが依存する時" -"にはそのうちの高々１個だけがインストールされていれば十分な ``ORM-bindings`` " -"を提供すると宣言していても構わないのです。" +"第二に、 Python のソフトウェアの中には zip アーカイブから直接に動作させること" +"をサポートするように書かれているものもありますが、やはり完全にインストールさ" +"れることを前提にして書かれたソースコードが今も普通です。 zip アーカイブからソ" +"フトウェアを走らせようと試みてこの仮定を崩すと、 (とりわけ失敗動作がサード" +"パーティのライブラリで起きる場合には) しばしば失敗動作がわかりにくく原因究明" +"が困難になるでしょう。この問題の最もありがちなふたつの根源は、 C 言語拡張を " +"zip アーカイブからインポートすることが CPython では *サポートされていない* こ" +"と (というのは、どんなプラットフォームの動的ローディング機構でもこのような動" +"作が直接にはサポートされていないから) 、および、 zip アーカイブから動作する際" +"には ``__file__`` 属性がもはや普通のファイルシステム上のファイルパスを参照し" +"ておらず、 zip アーカイブのファイルシステム上の置き場所のパスとアーカイブ内の" +"モジュールへの相対パスの両方を含んだ連結パスになることです。ソフトウェア内で" +"は抽象化された資源への API 群を正しく扱えたとしても、外部の部品とのインタフェ" +"イスは依然として実際にディスク上に存在するファイルがないと動作できないかもし" +"れません。" -#: ../source/specifications/core-metadata.rst:719 +#: ../source/specifications/binary-distribution-format.rst:413 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." +"Like metaclasses, monkeypatching and metapath importers, if you're not " +"already sure you need to take advantage of this feature, you almost " +"certainly don't need it. If you *do* decide to use it anyway, be aware that " +"many projects will require a failure to be reproduced with a fully installed " +"package before accepting it as a genuine bug." msgstr "" -"バージョンの宣言があっても構いませんが、 :doc:`バージョン指定子 ` に記述された規則に従ったものでなければなりません。もし指定されて" -"いなければ、配布物のバージョン番号が暗黙理に使われます。" +"メタクラスと同様に、モンキーパッチングとメタパスからのインポートは、この機能" +"を使う利点をあなたが本当に必要としていると確信しているのでなければ、おそらく" +"あなたはこの機能を使う必要がないと思われます。兎にも角にもこれを使う *意思を" +"固めた* のであれば、 (訳注、この機能を使った時に生じた) ある動作不良を真性の" +"バグであると認めてもらう前に、多くのプロジェクトではそれを完全インストールの" +"状態で再現するように要求されるであろうということを認識しておいてください。" -#: ../source/specifications/core-metadata.rst:734 -msgid "Obsoletes-Dist (multiple use)" -msgstr "Obsoletes-Dist (複数回の使用可)" +#: ../source/specifications/binary-distribution-format.rst:421 +#: ../source/specifications/core-metadata.rst:848 +#: ../source/specifications/dependency-specifiers.rst:476 +#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url.rst:67 +#: ../source/specifications/entry-points.rst:164 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:211 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:332 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/recording-installed-packages.rst:252 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1264 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "歴史" -#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "2013年2月: :pep:`427` を通じてこの仕様書が承認されました。" + +#: ../source/specifications/binary-distribution-format.rst:424 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." +"February 2021: The rules on escaping in wheel filenames were revised, to " +"bring them into line with what popular tools actually do." msgstr "" -"それぞれのエントリは、この配布物が出たことで旧式化した、従ってこれらふたつの" -"プロジェクトが同時にインストールされるべきではない distutils プロジェクトの配" -"布物を記述する文字列を含みます。" +"2021年2月: 他の普及しているツールが実際にやるのと同じやり方に合わせて、 " +"wheel のファイル名におけるエスケーピングの規則が修正されました。" -#: ../source/specifications/core-metadata.rst:745 +#: ../source/specifications/binary-distribution-format.rst:429 +msgid "Appendix" +msgstr "補遺" + +#: ../source/specifications/binary-distribution-format.rst:431 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "urlsafe-base64-nopad の実装の例::" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "コアとなるメタデータの仕様" + +#: ../source/specifications/core-metadata.rst:9 msgid "" -"Version declarations can be supplied. Version numbers must be in the format " -"specified in :doc:`version-specifiers`." +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" msgstr "" -"バージョンの宣言があっても構いません。バージョン番号は :doc:`バージョン指定" -"子 ` で指定されたフォーマットでなければなりません。" +"この後の仕様の中で定義されるフィールドは、正当かつ完全であって、変更の可能性" +"がないものと見做されるべきです。必須のフィールドは以下の通り:" -#: ../source/specifications/core-metadata.rst:750 -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:12 +msgid "``Metadata-Version``" msgstr "" -"このフィールドの最もよくある使い方は、例えば Gorgon 2.3 が Torqued Python " -"1.0 の一部として組み込まれた時のように、プロジェクトの名前が変更された場合で" -"しょう。 Torqued Python をインストールするなら、 Gorgon 配布物は削除されるべ" -"きです。" -#: ../source/specifications/core-metadata.rst:763 -msgid "Deprecated Fields" -msgstr "非推奨となったフィールド" +#: ../source/specifications/core-metadata.rst:13 +msgid "``Name``" +msgstr "``Name``" -#: ../source/specifications/core-metadata.rst:766 -msgid "Requires" -msgstr "要求事項" +#: ../source/specifications/core-metadata.rst:14 +msgid "``Version``" +msgstr "" -#: ../source/specifications/core-metadata.rst:769 -msgid "in favour of ``Requires-Dist``" -msgstr "``Requires-Dist`` に従って" +#: ../source/specifications/core-metadata.rst:16 +msgid "All the other fields are optional." +msgstr "これら以外のすべてのフィールドは必須のものではありません。" -#: ../source/specifications/core-metadata.rst:772 +#: ../source/specifications/core-metadata.rst:18 msgid "" -"Each entry contains a string describing some other module or package " -"required by this package." +"The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `) is based on the format of email headers. However, email formats " +"have been revised several times, and exactly which email RFC applies to " +"packaging metadata is not specified. In the absence of a precise definition, " +"the practical standard is set by what the standard library :mod:`python:" +"email.parser` module can parse using the :data:`~.python:email.policy." +"compat32` policy." msgstr "" -"それぞれのエントリは、このパッケージが必要とする他のモジュールやパッケージを" -"記述した文字列を含みます。" +"(:doc:`wheels ` および :doc:`インストール済みのプ" +"ロジェクト ` の両文書に含まれる) メタデータのた" +"めの標準的なファイルフォーマットは、電子メールのヘッダーのフォーマットに基い" +"ています。しかしながら、電子メールのフォーマットは何度か修正が入っています" +"が、正確にはどの電子メールの RFC がパッケージングのメタデータに適用されるのか" +"については指定がありません。精密な定義が欠落しているので、標準ライブラリの :" +"mod:`python:email.parser` モジュールが :data:`~.python:email.policy." +"compat32` のポリシーを用いて読み込むことができるものを実務上の標準として設定" +"しています。" -#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:27 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." +"Whenever metadata is serialised to a byte stream (for example, to save to a " +"file), strings must be serialised using the UTF-8 encoding." msgstr "" -"要求事項の文字列のフォーマットは、 ``import`` ステートメントで使うことができ" -"るモジュールやパッケージの名前のフォーマットと同一のもので、オプションとして" -"カッコ内に入れたバージョン宣言を伴うことがあります。" +"メタデータをバイト列 (例えばファイルに保存するために) にシリアル化する際には" +"いつでも、文字列を UTF-8 エンコーディングを用いてシリアル化しなければなりませ" +"ん。" -#: ../source/specifications/core-metadata.rst:779 +#: ../source/specifications/core-metadata.rst:30 msgid "" -"A version declaration is a series of conditional operators and version " -"numbers, separated by commas. Conditional operators must be one of \"<\", " -"\">\"', \"<=\", \">=\", \"==\", and \"!=\". Version numbers must be in the " -"format accepted by the ``distutils.version.StrictVersion`` class: two or " -"three dot-separated numeric components, with an optional \"pre-release\" tag " -"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\"," +"Although :pep:`566` defined a way to transform metadata into a JSON-" +"compatible dictionary, this is not yet used as a standard interchange " +"format. The need for tools to work with years worth of existing packages " +"makes it difficult to shift to a new format." msgstr "" -"バージョン宣言は、一連の比較演算子とバージョン番号をカンマで区切ったもので" -"す。比較演算子は、\"<\", \">\", \"<=\", \">=\", \"==\", \"!=\" のいずれかひと" -"つでなければなりません。バージョン番号は、オプションとして 'a' か 'b' の後ろ" -"に数字が続く形の \"pre-release\" タグを末尾につけた、二つか三つの数字部分を" -"ドットで区切ったものです。バージョン番号の例としては、 \"1.0\" や \"2.3a2\" " -"や \"1.3.99\" 、" +":pep:`566` でメタデータを JSON 互換の辞書型に変換する一つの方法を定義していま" +"すが、標準の交換フォーマットとしてはまだ使われていません。既に何年間も使われ" +"てきた既存のパッケージと共に動作するツールが必要なので、新しいフォーマットに" +"移行することは困難なのです。" -#: ../source/specifications/core-metadata.rst:787 +#: ../source/specifications/core-metadata.rst:35 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." +"*Interpreting old metadata:* In :pep:`566`, the version specifier field " +"format specification was relaxed to accept the syntax used by popular " +"publishing tools (namely to remove the requirement that version specifiers " +"must be surrounded by parentheses). Metadata consumers may want to use the " +"more relaxed formatting rules even for metadata files that are nominally " +"less than version 2.1." msgstr "" -"例えば \">1.0, !=1.3.4, <2.0\" という文字列が正当なバージョン宣言であるよう" -"に、比較演算子はいくつでも指定することができます。" +"*古い形式のメタデータを翻訳する:* :pep:`566` では、バージョン指定子フィールド" +"のフォーマット仕様がよく用いられている公開ツール群で使われる構文を受け入れる " +"(正確にはバージョン指定子が丸括弧で囲まれていなければならないという要求事項を" +"削除することによって) ようにと緩められました。メタデータを使う側としては、メ" +"タデータファイルが名ばかりのものとなっている 2.1 よりも前のバージョンであって" +"さえも、もっと寛容なフォーマット規則を使いたいかもしれません。" -#: ../source/specifications/core-metadata.rst:790 +#: ../source/specifications/core-metadata.rst:46 +msgid "Metadata-Version" +msgstr "Metadata-Version" + +#: ../source/specifications/core-metadata.rst:50 msgid "" -"All of the following are possible requirement strings: \"rfc822\", \"zlib " -"(>=1.1.4)\", \"zope\"." +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", and \"2.3\"." msgstr "" -"次に示すすべての要求仕様文字列 は実際に可能なものです: " -"\"rfc822\", \"zlib (>=1.1.4)\", \"zope\"。" +"ファイルフォーマットのバージョン; 正しいものは \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", と \"2.3\"。" -#: ../source/specifications/core-metadata.rst:793 +#: ../source/specifications/core-metadata.rst:53 msgid "" -"There’s no canonical list of what strings should be used; the Python " -"community is left to choose its own standards." +"Automated tools consuming metadata SHOULD warn if ``metadata_version`` is " +"greater than the highest version they support, and MUST fail if " +"``metadata_version`` has a greater major version than the highest version " +"they support (as described in the :ref:`Version specifier specification " +"`, the major version is the value before the first dot)." msgstr "" -"どのような文字列が用いられるべきであるかについては、公式に認められたリストは" -"ありません; 独自の標準を選択することが Python コミュニティに委ねられていま" -"す。" - -#: ../source/specifications/core-metadata.rst:806 -msgid "Provides" -msgstr "提供する" - -#: ../source/specifications/core-metadata.rst:809 -msgid "in favour of ``Provides-Dist``" -msgstr "``Provides-Dist`` を支持して " +"メタデータを処理する自動化ツールは、 ``metadata_version`` が自身のサポートす" +"る最大のものより大きい場合には警告を行うべきであり、かつ、 " +"``metadata_version`` が自身のサポートする最大のメジャーバージョンより大きいメ" +"ジャーバージョンを持つ場合には異常終了しなければなりません (:ref:`バージョン" +"指定子 ` に記述されている通り、メジャーバージョンとはバー" +"ジョンのうち最初のドットよりも前の部分です) 。" -#: ../source/specifications/core-metadata.rst:812 +#: ../source/specifications/core-metadata.rst:60 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 " -"the ones used in Requirements fields. A version declaration may be supplied " -"(without a comparison operator); the package’s version number will be " -"implied if none is specified." +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." msgstr "" -"それぞれのエントリには、そのパッケージをインストールすると提供されるであろう" -"パッケージなりモジュールなりについて記述した文字列を含みます。このような文字" -"列は、Requirements フィールドで使われるものに合致しているべきです。 (比較演算" -"子なしなら) バージョン宣言もあっても構いません; もしバージョン宣言がなけれ" -"ば、そのパッケージのバージョン番号を援用します。" - -#: ../source/specifications/core-metadata.rst:828 -msgid "Obsoletes" -msgstr "古くなった " +"より広く互換性を保つために、ビルドツールは、必要なフィールドをすべて含む前提" +"で最も古いバージョンのメタデータ仕様を使って配布物のメタデータを生成するとい" +"う選択を行なっても構いません。" -#: ../source/specifications/core-metadata.rst:831 -msgid "in favour of ``Obsoletes-Dist``" -msgstr "``Obsoletes-Dist`` に従って" +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:82 +#: ../source/specifications/core-metadata.rst:99 +#: ../source/specifications/core-metadata.rst:164 +#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:217 +#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:333 +#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:381 +#: ../source/specifications/core-metadata.rst:399 +#: ../source/specifications/core-metadata.rst:424 +#: ../source/specifications/core-metadata.rst:446 +#: ../source/specifications/core-metadata.rst:609 +#: ../source/specifications/core-metadata.rst:640 +#: ../source/specifications/core-metadata.rst:650 +#: ../source/specifications/core-metadata.rst:842 +msgid "Example::" +msgstr "例::" -#: ../source/specifications/core-metadata.rst:834 -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." +#: ../source/specifications/core-metadata.rst:72 +msgid "Name" msgstr "" -"それぞれのエントリには、あるパッケージなりモジュールなりがあることで、この" -"パッケージが使われなくなっている ということを記述する、すなわち、" -"これら二つのパッケージは同時にはインストールされるべきではないことを示す、そ" -"のような文字列が含まれます。バージョン宣言を書いておくことができます。" -#: ../source/specifications/core-metadata.rst:838 -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." +#: ../source/specifications/core-metadata.rst:75 +msgid "Added restrictions on format from the :ref:`name format `." msgstr "" -"このフィールドの最もよくある使い方は、例えば Gorgon 2.3 が Torqued Python " -"1.0 の一部として組み込まれた時のように、プロジェクトの名前が変更された場合で" -"しょう。 Torqued Python をインストールするなら、 Gorgon パッケージは削除され" -"るべきです。" +":ref:`名称のフォーマット ` から採用したフォーマットに対する制限" +"を追加した。" -#: ../source/specifications/core-metadata.rst:850 -msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +#: ../source/specifications/core-metadata.rst:78 +msgid "" +"The name of the distribution. The name field is the primary identifier for a " +"distribution. It must conform to the :ref:`name format specification `." msgstr "" -"2001年3月: :pep:`241` を通じてコアとなるメタデータ 1.0 が承認されました。" +"配布物の名称。name フィールドは配布物の最も基本的な識別子です。 :ref:`名称" +"フォーマット仕様 ` を満たしていなければなりません。" -#: ../source/specifications/core-metadata.rst:851 -msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`:" +#: ../source/specifications/core-metadata.rst:86 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -"2003年4月: :pep:`314` を通じてコアとなるメタデータ 1.1 が承認されました:" +"比較の目的のためにも、名前は比較の前に :ref:`正規化 ` さ" +"れているべきです。" -#: ../source/specifications/core-metadata.rst:852 -msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +#: ../source/specifications/core-metadata.rst:91 +msgid "Version" msgstr "" -"2010年2月: :pep:`345` を通じてコアとなるメタデータ 1.2 が承認されました。" -#: ../source/specifications/core-metadata.rst:853 -msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +#: ../source/specifications/core-metadata.rst:95 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." msgstr "" -"2018年2月: :pep:`566` を通じてコアとなるメタデータ 2.1 が承認されました。" - -#: ../source/specifications/core-metadata.rst:855 -msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." -msgstr "``Description-Content-Type`` と ``Provides-Extra`` を追加しました。" +"配布物のバージョン番号を格納する文字列。このフィールドは :ref:`バージョン指定" +"子仕様 ` で規定されるフォーマットでなければなりません。" -#: ../source/specifications/core-metadata.rst:856 -msgid "Added canonical method for transforming metadata to JSON." -msgstr "メタデータを JSON に変換する正規化された方法を追加しました。" +#: ../source/specifications/core-metadata.rst:107 +msgid "Dynamic (multiple use)" +msgstr "Dyanamic (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:857 -msgid "Restricted the grammar of the ``Name`` field." -msgstr "``Name`` フィールドの文法に制限を加えました。" +#: ../source/specifications/core-metadata.rst:111 +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 "" +"別のコアとなるメタデータのフィールドの名前を包含した文字列。フィールド名の " +"``Name`` ・ ``Version`` ・ ``Metadata-Version`` をこのフィールドに指定しては" +"なりません。" -#: ../source/specifications/core-metadata.rst:859 -msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +#: ../source/specifications/core-metadata.rst:115 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" msgstr "" -"2020年10月: :pep:`643` を通じてコアとなるメタデータ 2.2 が承認されました。" +"ソースコード配布物のメタデータ中に見つかった場合には、以下の規則を適用します:" -#: ../source/specifications/core-metadata.rst:861 -msgid "Added the ``Dynamic`` field." -msgstr "``Dynamic`` フィールドを追加しました。" +#: ../source/specifications/core-metadata.rst:118 +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 " +"field is not in the sdist, and not marked as ``Dynamic``, then it MUST NOT " +"be present in the wheel." +msgstr "" +"フィールドが ``Dynamic`` と *マークされていない* 場合は、 sdist からビルドさ" +"れたどの wheel であっても、そのフィールドの値が sdist での値と一致しなければ" +"なりません。そのフィールドが sdist には存在せず、かつ、 ``Dynamic`` とマーク" +"されていない場合には、そのようなフィールドは wheel に出現してはなりません。" -#: ../source/specifications/core-metadata.rst:863 -msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +#: ../source/specifications/core-metadata.rst:122 +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 "" -"2022年3月: :pep:`685` を通じてコアとなるメタデータ 2.3 が承認されました。" +"フィールドが ``Dynamic`` とマークされている場合、 (ひとつも存在しない場合も含" +"めて) sdist からビルドされた wheel 内のどんな正当な値を取っても構いません。" -#: ../source/specifications/core-metadata.rst:865 -msgid "Restricted extra names to be normalized." -msgstr "その他の名称 の標準化に制限を加えました。" +#: ../source/specifications/core-metadata.rst:125 +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 "" +"sdist のメタデータバージョンがバージョン 2.2 よりも古い場合には、すべての" +"フィールドが ``Dynamic`` であると指定されたかのように (つまり、その sdist か" +"らビルドされた wheel のメタデータに何も特別な制約がないかのように) 取り扱うべ" +"きです。" -#: ../source/specifications/core-metadata.rst:869 -msgid "reStructuredText markup: https://docutils.sourceforge.io/" -msgstr "reStructuredText マークアップ言語: https://docutils.sourceforge.io/" +#: ../source/specifications/core-metadata.rst:129 +msgid "" +"In any context other than a source distribution, ``Dynamic`` is for " +"information only, and indicates that the field value was calculated at wheel " +"build time, and may not be the same as the value in the sdist or in other " +"wheels for the project." +msgstr "" +"ソースコード配布物を除くすべての文脈で、 ``Dynamic`` は情報提供の目的のみであ" +"り、そのフィールドの値がビルドの際に計算されたものであって、 sdist や同じプロ" +"ジェクトでも他の wheel ファイルでは異なる場合があることを示します。" -#: ../source/specifications/core-metadata.rst:874 -msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" -msgstr "RFC 822 長形式ヘッダフィールド: :rfc:`822#section-3.1.1`" +#: ../source/specifications/core-metadata.rst:134 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "``Dynamic`` の詳細かつ完全な意味は :pep:`643` に記述されています。" -#: ../source/specifications/dependency-specifiers.rst:7 -msgid "Dependency specifiers" -msgstr "依存関係指定子" +#: ../source/specifications/core-metadata.rst:139 +msgid "Platform (multiple use)" +msgstr "Platform (複数回の使用可)" -#: ../source/specifications/dependency-specifiers.rst:9 +#: ../source/specifications/core-metadata.rst:143 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"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 "" -"元々は :pep:`508` で指定されていた依存関係指定子のフォーマットを、この説明文" -"書は記述します。" +"Platform の仕様は、その配布物がサポートするオペレーティングシステムを記述した" +"もので、 \"Operating System\" Trove 分類子には記載されていないもの。後述の " +"\"分類子 \" を見てください。" -#: ../source/specifications/dependency-specifiers.rst:12 -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." -msgstr "" -"依存関係 の任務は、 pip [#pip]_ のようなツールがインストールする" -"べき正しいパッケージを探し出すことができるようにすることです。これは時には大" -"変に曖昧で名称を指定するだけであったり、別の時には非常に限定的でインストール" -"するべき特定のファイルを参照したりします。場合によっては、依存関係 " -" がひとつのプラットフォームでのみ妥当であったり、いくつかのバー" -"ジョンだけが受け入れ可能であったりするので、(依存関係 を記述す" -"る) 言語としてはこれらすべてのケースを記述できるものでなければなりません。" +#: ../source/specifications/core-metadata.rst:147 +#: ../source/specifications/core-metadata.rst:471 +#: ../source/specifications/core-metadata.rst:495 +#: ../source/specifications/core-metadata.rst:536 +#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:725 +#: ../source/specifications/core-metadata.rst:755 +#: ../source/specifications/core-metadata.rst:796 +#: ../source/specifications/core-metadata.rst:818 +msgid "Examples::" +msgstr "例::" -#: ../source/specifications/dependency-specifiers.rst:18 +#: ../source/specifications/core-metadata.rst:155 +msgid "Supported-Platform (multiple use)" +msgstr "Supported-Platform (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:159 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." +"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 " +"binary distribution was compiled. The semantics of the Supported-Platform " +"field are not specified in this PEP." msgstr "" -"定義された言語は、簡潔な行単位のフォーマットであって pip の requirements ファ" -"イルで既に広く使われているものですが、そのようなファイル群を許容するようなコ" -"マンドラインオプションを指定することはしていません。ひとつ注意しなければなら" -"ないのは、 :ref:`バージョン指定子仕様 ` で指定されている" -"ような URL を参照する形式は実は pip では実装されていないのに、現在の pip の本" -"来のフォーマットよりもむしろそちらのフォーマットを使っているという点です。" - -#: ../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:11 -msgid "Specification" -msgstr "仕様" +"PKG-INFO ファイルを含むバイナリ配布物は、内包するメタデータの中の Supported-" +"Platform フィールドを使って当該バイナリ配布物がどの OS や CPU 向けにコンパイ" +"ルされたかを指定することになるでしょう。 Supported-Platform フィールドのセマ" +"ンティクスは PEP には定義されたものがありません。" -#: ../source/specifications/dependency-specifiers.rst:31 -msgid "All features of the language shown with a name based lookup::" -msgstr "この言語のすべての機能を、名前に基づいた参照とともに示します::" +#: ../source/specifications/core-metadata.rst:173 +msgid "Summary" +msgstr "Summary" -#: ../source/specifications/dependency-specifiers.rst:35 -msgid "A minimal URL based lookup::" -msgstr "最低限の URL に基づいた参照::" +#: ../source/specifications/core-metadata.rst:177 +msgid "A one-line summary of what the distribution does." +msgstr "その配布物が何をするものかを１行で記述した要約。" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "Concepts" -msgstr "概念" +#: ../source/specifications/core-metadata.rst:197 +msgid "This field may be specified in the message body instead." +msgstr "このフィールドの代わりにメッセージ本体で指定しても構いません。" -#: ../source/specifications/dependency-specifiers.rst:42 +#: ../source/specifications/core-metadata.rst:200 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." +"A longer description of the distribution that can run to several " +"paragraphs. Software that deals with metadata should not assume any maximum " +"size for this field, though people shouldn't include their instruction " +"manual as the description." msgstr "" -"依存関係の指定では、常に、配布物の名前を指定します。名前で指定された配布物で" -"特定の追加機能を有効にするように依存関係を拡張するような追加物 を含ん" -"でいても構いません。インストールされたバージョンをバージョンリミットで制御す" -"ることもできますし、特定のアーティファクトをインストールするために URL を与え" -"ることもできます。依存関係は最終的に環境マーカを用いて条件別に作成することも" -"できます。" +"配布物に関する長めの説明文で、いくつかの段落に渡ってもかまいません。取扱説明" +"書並みの記述をするべきではありませんが、メタデータを扱うソフトウェアはこの" +"フィールドに最大長さがあるものと仮定すべきではありません。" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "Grammar" -msgstr "文法" +#: ../source/specifications/core-metadata.rst:205 +msgid "" +"The contents of this field can be written using reStructuredText markup " +"[1]_. For programs that work with the metadata, supporting markup is " +"optional; programs can also display the contents of the field as-is. This " +"means that authors should be conservative in the markup they use." +msgstr "" +"このフィールドの内容は、 reStructuredText マークアップ [1]_ を使って書いても" +"構いません。メタデータを取り扱うプログラムの側ではマークアップをサポートして" +"もしなくてもかまわず、サポートしない場合にはこのフィールドの内容をそのまま表" +"示することも可能です。つまり、作者の側は、自分が採用するマークアップ言語につ" +"いては保守的であるべきだということになります。" -#: ../source/specifications/dependency-specifiers.rst:51 +#: ../source/specifications/core-metadata.rst:211 msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +"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 " +"pipe (\"|\") char. As a result, the Description field is encoded into a " +"folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -"最初に文法について簡単に触れた後、それぞれの節の意味論 について深" -"く掘り下げることにしましょう。" +"空行および RFC 822 に従う字下げをサポートするために、すべての CRLF 文字には７" +"個の空白文字と１個のパイプ文字 (\"|\") がこの順に並ぶ文字列が後続しなければな" +"りません。その結果として、Description フィールドが RFC 822 構文解析器 [2]_ で" +"解析可能な形の改行可能なフィールドにエンコードされます。" -#: ../source/specifications/dependency-specifiers.rst:54 +#: ../source/specifications/core-metadata.rst:228 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 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 "" -"配布物の仕様は ASCII テキストで書かれています。厳密な文法としては parsley " -"[#parsley]_ の文法を使っています。この仕様は、コメントや継続による複数行サ" -"ポートやその他の機能の枠組みを与えるもっと大きなシステムの中に組み込まれるこ" -"とを期待しています。" +"このエンコーディングが意味するところは、その折り畳まれたフィールドをRFC822 読" +"み取り器で読み取る時には、CRLF と７個の空白文字とそれに引き続くパイプ文字が出" +"現するたびにそれを単独の CRLF に置き換えなければならないということです。" -#: ../source/specifications/dependency-specifiers.rst:59 +#: ../source/specifications/core-metadata.rst:232 msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +"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/dependency-specifiers.rst:62 +#: ../source/specifications/core-metadata.rst:241 +msgid "Description-Content-Type" +msgstr "Description-Content-Type" + +#: ../source/specifications/core-metadata.rst:245 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." msgstr "" -":ref:`バージョン指定子仕様 ` の規則に従ってバージョンを指" -"定しても構いません。(ノート: URI は :rfc:`std-66 <3986>` で定義されていま" -"す)::" +"配布物の説明で使われるマークアップ構文 (もしあれば) を述べる文字列で、ツール" +"の側が頭の良いやり方で説明を表示することができます。" -#: ../source/specifications/dependency-specifiers.rst:73 +#: ../source/specifications/core-metadata.rst:248 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"Historically, PyPI supported descriptions in plain text and " +"`reStructuredText (reST) `_, and could render reST into HTML. However, it is " +"common for distribution authors to write the description in `Markdown " +"`_ (:rfc:`7763`) as many code " +"hosting sites render Markdown READMEs, and authors would reuse the file for " +"the description. PyPI didn't recognize the format and so could not render " +"the description correctly. This resulted in many packages on PyPI with " +"poorly-rendered descriptions when Markdown is left as plain text, or worse, " +"was attempted to be rendered as reST. This field allows the distribution " +"author to specify the format of their description, opening up the " +"possibility for PyPI and other tools to be able to render Markdown and other " +"formats." msgstr "" -"環境マーカを使うことで、ある仕様が特定の環境でのみ有効であることを示すことが" -"できます::" +"歴史的には PyPI はプレーンテキストおよび `reStructuredText (reST) `_ での " +"description をサポートし、 reST を HTML として表示することができました。しか" +"しながら、多くのソースコード管理サイトが Markdown の README を表示するように" +"なったので、配布物の作者たちが description を `Markdown `_ (:rfc:`7763`) で書くことが普通にな" +"り、作者たちはそのファイルを description として再利用するようになってきまし" +"た。 PyPI はこのフォーマットを認識せず、従って description の内容を正しく表示" +"することができませんでした。その結果、 PyPI 上の多くのパッケージで Markdown " +"がプレーンテキストとして、もっと悪い場合には reST として解釈して、惨めな表示" +"になっていました。このフィールドは配布物の作者がその description のフォーマッ" +"トを指定できるようにしますので、 PyPI やその他のツールが Markdown やその他の" +"フォーマットを正しく表示できるようになる可能性を広げます。" -#: ../source/specifications/dependency-specifiers.rst:102 +#: ../source/specifications/core-metadata.rst:261 msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +"The format of this field is the same as the ``Content-Type`` header in HTTP " +"(i.e.: `RFC 1341 `_). Briefly, this means that it has a ``type/subtype`` part and then " +"it can optionally have a number of parameters:" msgstr "" -"配布物のうちの必須ではない部分については extras フィールドを使って指定するこ" -"とができます::" +"このフィールドのフォーマットは HTTP (すなわち `RFC 1341 `_) における ``Content-Type`` ヘッダの" +"それと同じです。端的に言えば、これは ``type/subtype`` の部分を持っていて、オ" +"プションとしていくつかのパラメータを取ることができるというものです:" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Restrictions on names for extras is defined in :pep:`685`." -msgstr "追加物の名前に対する制限事項は :pep:`685` で定義されています。" +#: ../source/specifications/core-metadata.rst:267 +msgid "Format::" +msgstr "フォーマット::" -#: ../source/specifications/dependency-specifiers.rst:113 -msgid "Giving us a rule for name based requirements::" -msgstr "私たちに名前に基づいた要求仕様を与えてください::" +#: ../source/specifications/core-metadata.rst:271 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "``type/subtype`` 部分はいくつかの正当な値を取ります:" -#: ../source/specifications/dependency-specifiers.rst:117 -msgid "And a rule for direct reference specifications::" -msgstr "そして、直接参照に用いる要求仕様のための規則はこちら::" +#: ../source/specifications/core-metadata.rst:273 +msgid "``text/plain``" +msgstr "``text/plain``" -#: ../source/specifications/dependency-specifiers.rst:121 -msgid "Leading to the unified rule that can specify a dependency.::" -msgstr "依存関係を指定することができる統一規則への案内はこちら::" +#: ../source/specifications/core-metadata.rst:274 +msgid "``text/x-rst``" +msgstr "``text/x-rst``" -#: ../source/specifications/dependency-specifiers.rst:126 -msgid "Whitespace" -msgstr "空白文字 " +#: ../source/specifications/core-metadata.rst:275 +msgid "``text/markdown``" +msgstr "``text/markdown``" -#: ../source/specifications/dependency-specifiers.rst:128 +#: ../source/specifications/core-metadata.rst:277 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"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 " +"assumed to be ``UTF-8``." msgstr "" -"行を分割するものではない空白文字には特に意味はなく、ほとんどの場合には必須で" -"はないものです。唯一の例外は、 URL による要求事項の末尾を検出するためのもので" -"す。" - -#: ../source/specifications/dependency-specifiers.rst:132 -msgid "Names" -msgstr "名前 " +"``charset`` パラメータは、description のキャラクターのエンコーディングを指定" +"するために使われます。唯一の正当な値は ``UTF-8`` です。省略時には ``UTF-8`` " +"であるものと仮定します。" -#: ../source/specifications/dependency-specifiers.rst:134 +#: ../source/specifications/core-metadata.rst:281 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::" +"Other parameters might be specific to the chosen subtype. For example, for " +"the ``markdown`` subtype, there is an optional ``variant`` parameter that " +"allows specifying the variant of Markdown in use (defaults to ``GFM`` if not " +"specified). Currently, two variants are recognized:" msgstr "" -"Python の配布物の名前は、現時点では :pep:`345` で定義されています。名前は配布" -"物の最も基本的な識別子として働きます。(名前は) あらゆる依存関係の指定に出現" -"し、それだけで十分に指定することができます。しかしながら、 PyPI では名前に厳" -"密な制約を課しています - 名前は大文字小文字を区別しない正規表現に合致しなけれ" -"ば受け入れられません。従って、この説明文書では、その正規表現に合致する識別子" -"だけを受け入れ可能な値として扱うことにしましょう。名前の完全な再定義はメタ" -"データ PEP として将来に出現するかもしれません。ここでいう (re.IGNORECASE とと" -"もに評価されるべき) 正規表現とは、次のようなものです::" +"サブタイプを選択するために他のパラメータが指定される場合もあります。例えば、 " +"``markdown`` サブタイプを指定する際に、使われている Markdown の異種 (指定がな" +"い場合にはデフォルトでは ``GFM``) を指定することができるオプションの " +"``variant`` パラメータが存在します。現時点ではふたつの異種が認識されます:" -#: ../source/specifications/dependency-specifiers.rst:146 -msgid "Extras" -msgstr "追加物 " +#: ../source/specifications/core-metadata.rst:286 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "``GFM`` すなわち :rfc:`Github 流の Markdown <7764#section-3.2>`" -#: ../source/specifications/dependency-specifiers.rst:148 +#: ../source/specifications/core-metadata.rst:287 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr ":rfc:`CommonMark <7764#section-3.5>` を指定する ``CommonMark``" + +#: ../source/specifications/core-metadata.rst:305 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::" +"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 "" -"追加物とは、配布物の必須ではない部分のことです。配布物では追加物を幾つでも指" -"定することができ、追加物が依存関係の指定場所で使われた **場合** には、それぞ" -"れの追加物が配布物の追加的な依存関係を宣言する結果になります。例えば::" +"``Description-Content-Type`` が指定されていない場合には、アプリケーションとし" +"ては、まず ``text/x-rst; charset=UTF-8`` として表示を試み、正当な rst ではな" +"い場合に ``text/plain`` にフォールバックするべきです。" -#: ../source/specifications/dependency-specifiers.rst:155 +#: ../source/specifications/core-metadata.rst:309 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." +"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 "" -"追加物 の依存関係の合併とは、その追加物が添付されている配布物 " -" の依存関係と一緒に定義されることです。上に示した例では、結果と" -"して requests がインストールされることになり、requests は自身の依存関係を持つ" -"ので requests の \"security\" 追加物 に列挙されたすべての依存関係 " -"(先) もインストールされることになります。" +"``Description-Content-Type`` が認識できない値である場合には、内容の型が " +"``text/plain`` であるものと仮定します (とはいえ、認識できない値であれば何で" +"あっても PyPI が拒否することになるでしょう) 。" -#: ../source/specifications/dependency-specifiers.rst:160 +#: ../source/specifications/core-metadata.rst:313 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"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 "" -"複数の追加物 が列挙されている場合には、すべての依存関係の合併集合が依" -"存関係になります。" +"``Description-Content-Type`` が ``text/markdown`` で、 ``variant`` が指定され" +"ない場合や認識できない値が指定された場合には、 ``variant`` が ``GFM`` である" +"ものと仮定されます。" -#: ../source/specifications/dependency-specifiers.rst:163 -#: ../source/specifications/simple-repository-api.rst:888 -msgid "Versions" -msgstr "バージョン指定子" +#: ../source/specifications/core-metadata.rst:317 +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 "" +"上記の最後の例を見ると ``charset`` はデフォルトでは ``UTF-8`` であり、 " +"``variant`` はデフォルトでは ``GFM`` ですので、それ以前の例と同等であるという" +"ことになります。" -#: ../source/specifications/dependency-specifiers.rst:165 +#: ../source/specifications/core-metadata.rst:326 +msgid "Keywords" +msgstr "キーワード" + +#: ../source/specifications/core-metadata.rst:330 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." +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." msgstr "" -"バージョン番号やその比較方法について、詳しくは :ref:`バージョン指定子仕様 " -"` をみてください。バージョン仕様は、配布物のバージョンと" -"して使うことができる範囲を定めています。これは、名前によって参照される配布物" -"にのみ適用されるのであって、URL を通じて指定されるものには該当しません。バー" -"ジョン番号の比較は、また、マーカー機能においても使われます。バージョンの周囲" -"にある必須でない括弧は :pep:`345` との互換性を保つために存在していますが、そ" -"のようなものを生成すべきではなくて受容するだけにとどめるべきです。" +"より大きなカタログで配布物を検索する助けとなるべく使用される、コンマで区切ら" +"れた追加のキーワードのリスト。" -#: ../source/specifications/dependency-specifiers.rst:174 -msgid "Environment Markers" -msgstr "環境マーカ" +#: ../source/specifications/core-metadata.rst:339 +msgid "" +"The specification previously showed keywords separated by spaces, but " +"distutils and setuptools implemented it with commas. These tools have been " +"very widely used for many years, so it was easier to update the " +"specification to match the de facto standard." +msgstr "" +"以前にお見せした仕様ではキーワードを区切るのに空白文字を使っていましたが、 " +"distutils と setuptools はコンマで区切ります。これらのツールは多年に渡って非" +"常に広く使われていますので、仕様をデファクト標準に合わせる形で更新する方が簡" +"単でした。" -#: ../source/specifications/dependency-specifiers.rst:176 +#: ../source/specifications/core-metadata.rst:348 +msgid "Home-page" +msgstr "Home-page" + +#: ../source/specifications/core-metadata.rst:352 +msgid "A string containing the URL for the distribution's home page." +msgstr "配布物のホームページを示す URL を含んだ文字列。" + +#: ../source/specifications/core-metadata.rst:361 +msgid "Download-URL" +msgstr "Download-URL" + +#: ../source/specifications/core-metadata.rst:365 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 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 "" -"環境マーカは、依存関係の指定においてその依存関係がいつ使われるべきであるかを" -"記述する規則を提供します。例えば、あるパッケージが argparse を必要とするとし" -"ましょう。Python 2.7 では argparse は常に存在します。もっと古いバージョンの " -"Python では依存関係としてインストールされなければなりません。これは次のように" -"表現することができます::" +"そこからこのバージョンの配布物をダウンロードすることができる URL を含んだ文字" +"列。 (これが意味するところは、 URL は何か \".../BeagleVote-latest.tgz\" のよ" +"うなものでは駄目で、 \".../BeagleVote-0.45.tgz\" のようにバージョンを含むもの" +"でなければならないということです。)" + +#: ../source/specifications/core-metadata.rst:374 +msgid "Author" +msgstr "Author" -#: ../source/specifications/dependency-specifiers.rst:183 +#: ../source/specifications/core-metadata.rst:378 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A string containing the author's name at a minimum; additional contact " +"information may be provided." msgstr "" -"マーカ表現は評価されると真か偽に帰着します。偽と評価された場合には、その依存" -"関係の指定は無視されなければなりません。" +"少なくとも作者の名前を含む文字列で、連絡先となる情報を追加しても構いません。" -#: ../source/specifications/dependency-specifiers.rst:186 +#: ../source/specifications/core-metadata.rst:391 +msgid "Author-email" +msgstr "Author-email" + +#: ../source/specifications/core-metadata.rst:395 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 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 "" -"マーカ言語は Python そのものに触発されたもので、セキュリティ上の脆弱性になり" -"かねない任意コードの実行を伴わずに安全に評価を行うことができるので選ばれまし" -"た。マーカは:pep:`345` で初めて標準化されました。この説明文書では、 :pep:" -"`426` に記述されたデザインに見られるいくつかの問題点を修正しています。" +"作者の電子メールアドレスを含む文字列。 RFC-822 の ``From:`` ヘッダの記述形式" +"として正当な形で名前と電子メールアドレスを含んでいても構いません。" -#: ../source/specifications/dependency-specifiers.rst:191 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:450 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::" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" msgstr "" -"マーカ表現の比較は比較演算子によって分類されます。 の中に入って" -"いない 演算子は、 Python における文字列でのそれと同様に動作しま" -"す。 演算子は、定義されている場合 (つまり両側に正当はバージョン" -"指定子を伴う場合) には、 :ref:`バージョン指定子仕様 ` の" -"バージョン比較規則を採用しています。演算子の動作がこの仕様で定義されておら" -"ず、かつ、その演算子が Python に存在する場合には、当該演算子は Python での動" -"作にフォールバックします。そうでない場合にはエラーを発生させるべきです。例え" -"ば、次の表現はエラーを発生させる結果となるでしょう::" +"RFC-822 によれば、このフィールドは、複数の電子メールアドレスをコンマで区切っ" +"て記述しても構いません::" -#: ../source/specifications/dependency-specifiers.rst:204 +#: ../source/specifications/core-metadata.rst:413 +msgid "Maintainer" +msgstr "メンテナ" + +#: ../source/specifications/core-metadata.rst:417 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 string containing the maintainer's name at a minimum; additional contact " +"information may be provided." msgstr "" -"ユーザ側から供給された定数は、常に ``'`` または ``\"`` なる引用記号を伴った文" -"字列として符号化されます。バックスラッシュによるエスケープは定義されていませ" -"んが、現存する実装ではサポートされているということを忘れないでください。この" -"仕様には (バックスラッシュエスケープは) 含まれていませんが、それは、複雑性を" -"増加させてしまうことと、現時点では目に見えるほどの必要性がないことが理由で" -"す。同様に、非 ASCII 文字のサポートも定義していません: 我々が参照するようなラ" -"ンタイムのすべての変数は、 ASCII 文字のみで構成されているものと期待されていま" -"す。" +"少なくともメンテナの名前を含む文字列で、連絡先となる情報を追加しても構いませ" +"ん。" -#: ../source/specifications/dependency-specifiers.rst:211 +#: ../source/specifications/core-metadata.rst:420 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." +"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 "" -"\"os_name\" のようなマーカの文法内の変数は、 Python のランタイム内でルック" -"アップすることで値へと解決されます。 \"extra\" を例外として、すべての値は現在" -"のすべてのバージョンの Python で定義されています - もし値が定義されていなけれ" -"ば、それはマーカの実装のエラーです。" +"当該プロジェクトが元々の作者とは異なる誰かによって保守されている場合にこの" +"フィールドを使うことを想定しているということを覚えておいてください: もし " +"``Author`` と同一人物であれば、このフィールドを省略するべきです。" -#: ../source/specifications/dependency-specifiers.rst:216 +#: ../source/specifications/core-metadata.rst:434 +msgid "Maintainer-email" +msgstr "Maintainer-email" + +#: ../source/specifications/core-metadata.rst:438 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"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 "" -"未知の変数は、評価して真 か偽 となる比較の結果を返すのではな" -"く、エラーを生成しなければなりません。" +"メンテナの電子メールアドレスを含む文字列。 RFC-822 の ``From:`` ヘッダの記述" +"形式として正当な形で名前と電子メールアドレスを含んでいても構いません。" -#: ../source/specifications/dependency-specifiers.rst:219 +#: ../source/specifications/core-metadata.rst:442 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." +"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 "" -"特定の Python 実装で値を計算することができない変数は、バージョンについては " -"``0`` として、その他のすべての変数については空文字列として評価されるべきで" -"す。" +"当該プロジェクトが元々の作者とは異なる誰かによって保守されている場合にこの" +"フィールドを使うことを想定しているということを覚えておいてください: もし " +"``Author-email`` と同一であれば、このフィールドを省略するべきです。" -#: ../source/specifications/dependency-specifiers.rst:223 +#: ../source/specifications/core-metadata.rst:460 +msgid "License" +msgstr "License" + +#: ../source/specifications/core-metadata.rst:464 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." +"Text indicating the license covering the distribution where the license is " +"not a selection from the \"License\" Trove classifiers. See :ref:" +"`\"Classifier\" ` below. This field may also be used to " +"specify a particular version of a license which is named via the " +"``Classifier`` field, or to indicate a variation or exception to such a " +"license." msgstr "" -"\"extra\" 変数は、扱いが特別です。それは wheel ファイルにおいて、その wheel " -"の ``METADATA`` ファイル内の特定の追加物 にどの仕様を適用するべきであ" -"るかを知らせるために使われますが、 ``METADATA`` ファイルの様式が :pep:`426` " -"のドラフトバージョンに基づいているので、現時点ではその仕様が存在していないの" -"です。それにも関わらず、この特別な扱いが行われる場所ではない文脈においては、 " -"\"extra\" 変数はその他の未知の変数と同様にエラーに帰着するべきです。" - -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Marker" -msgstr "マーカ " +"\"License\" Trove 分類子から選択したものではないライセンスの場合は、配布物を" +"カバーするライセンスを示すテキスト。後述の :ref:`\"Classifier\" ` を見てください。このフィールドは、 ``Classifier`` フィールドを経" +"由して名指しされたライセンスの特定のバージョンを指定したり、そのようなライセ" +"ンスに対する変種や例外事項を示したりするのに使っても構いません。" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "Python equivalent" -msgstr "Python 同等物" +#: ../source/specifications/core-metadata.rst:484 +msgid "Classifier (multiple use)" +msgstr "Classifier (複数回の使用可)" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "Sample values" -msgstr "値の例" +#: ../source/specifications/core-metadata.rst:488 +msgid "" +"Each entry is a string giving a single classification value for the " +"distribution. Classifiers are described in :pep:`301`, and the Python " +"Package Index publishes a dynamic list of `currently defined classifiers " +"`__." +msgstr "" +"それぞれのエントリは、当該配布物を分類する値をひとつ与える文字列です。分類子" +"については :pep:`301` に記述されていて、The Python Package Index は `現在定義" +"されている分類子 `__ という動的なリストを公開" +"しています。" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``os_name``" -msgstr "``OS の名称 ``" +#: ../source/specifications/core-metadata.rst:493 +#: ../source/specifications/core-metadata.rst:583 +#: ../source/specifications/core-metadata.rst:723 +#: ../source/specifications/core-metadata.rst:748 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "このフィールドでは、セミコロンの後に環境指標を続けても構いません。" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid ":py:data:`os.name`" -msgstr ":py:data:`os.name`" +#: ../source/specifications/core-metadata.rst:504 +msgid "Requires-Dist (multiple use)" +msgstr "Requires-Dist (複数回の使用可)" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``posix``, ``java``" -msgstr "``posix``, ``java``" +#: ../source/specifications/core-metadata.rst:507 +#: ../source/specifications/core-metadata.rst:570 +#: ../source/specifications/core-metadata.rst:695 +#: ../source/specifications/core-metadata.rst:737 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" +"フィールドの仕様は、人気のある公開ツール群が用いる構文を許容するように緩めら" +"れました。" -#: ../source/specifications/dependency-specifiers.rst:239 -msgid "``sys_platform``" -msgstr "``sys_platform``" +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" +"それぞれのエントリは、この配布物が要求する他の distutils のプロジェクトを名指" +"しする文字列を含みます。" -#: ../source/specifications/dependency-specifiers.rst:240 -msgid ":py:data:`sys.platform`" -msgstr ":py:data:`sys.platform`" +#: ../source/specifications/core-metadata.rst:514 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "要求事項を示す文字列のフォーマットは、１個から４個の部分を含みます:" -#: ../source/specifications/dependency-specifiers.rst:241 +#: ../source/specifications/core-metadata.rst:516 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." msgstr "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (\"linux\" は Python3 か" -"ら、\"linux2\" は Python2 からであることに注意してください)" +"``Name:`` フィールドと同じフォーマットのプロジェクト名。これだけが必須部分で" +"す。" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``platform_machine``" -msgstr "``platform_machine``" +#: ../source/specifications/core-metadata.rst:518 +msgid "" +"A comma-separated list of 'extra' names. These are defined by the required " +"project, referring to specific features which may need extra dependencies. " +"The names MUST conform to the restrictions specified by the ``Provides-Extra:" +"`` field." +msgstr "" +"コンマ区切りの '追加の' 名前のリスト。これらは、追加的な依存先を必要とする特" +"定の機能に応じて、要求されたプロジェクトによって定義されます。この名前は、 " +"``Provides-Extra:`` フィールドで指定された制約事項に従うものでなければなりま" +"せん。" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid ":py:func:`platform.machine()`" -msgstr ":py:func:`platform.machine()`" +#: ../source/specifications/core-metadata.rst:522 +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/dependency-specifiers.rst:245 -msgid "``x86_64``" -msgstr "``x86_64``" +#: ../source/specifications/core-metadata.rst:525 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" +"セミコロンの後ろに環境マーカ。要求事項が必要となるのが指定された条件の時のみ" +"であることを示します。" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``platform_python_implementation``" -msgstr "``platform_python_implementation``" +#: ../source/specifications/core-metadata.rst:528 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "許容されるフォーマットの詳細については :pep:`508` を見てください。" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid ":py:func:`platform.python_implementation()`" -msgstr ":py:func:`platform.python_implementation()`" +#: ../source/specifications/core-metadata.rst:530 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" +"プロジェクト名は、 `Python パッケージインデックス `_ に" +"出現する名前に対応していなければなりません。" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``CPython``, ``Jython``" -msgstr "``CPython``, ``Jython``" +#: ../source/specifications/core-metadata.rst:533 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" +"バージョン指定子は :doc:`version-specifiers` に記述された規則に従っていなけれ" +"ばなりません。" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``platform_release``" -msgstr "``platform_release``" +#: ../source/specifications/core-metadata.rst:547 +msgid "Requires-Python" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid ":py:func:`platform.release()`" -msgstr ":py:func:`platform.release()`" +#: ../source/specifications/core-metadata.rst:551 +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 "" +"このフィールドは、配布物が互換性を持つ Python のバージョン (複数可) を指定し" +"ます。インストールツールは、プロジェクトのインストールするべきバージョンを選" +"択する時にこのフィールドを参照しても構いません。" -#: ../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/core-metadata.rst:555 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" +"値は、 :doc:`version-specifiers` で指定されたフォーマットでなければなりませ" +"ん。" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``platform_system``" -msgstr "``platform_system``" +#: ../source/specifications/core-metadata.rst:557 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" +"例えば、ある配布物が :ref:`f-strings ` を使っているなら、" +"次のように指定することで Python < 3.6 上にインストールするのを抑止してもかま" +"いません::" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid ":py:func:`platform.system()`" -msgstr ":py:func:`platform.system()`" +#: ../source/specifications/core-metadata.rst:562 +msgid "This field cannot be followed by an environment marker." +msgstr "このフィールドでは、環境マーカを後ろに付けることはできません。" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``Linux``, ``Windows``, ``Java``" -msgstr "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/core-metadata.rst:567 +msgid "Requires-External (multiple use)" +msgstr "Requires-External (複数回の使用可)" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "``platform_version``" -msgstr "``platform_version``" +#: ../source/specifications/core-metadata.rst:574 +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 " +"to downstream project maintainers, and has no semantics which are meaningful " +"to the ``distutils`` distribution." +msgstr "" +"それぞれのエントリは、その配布物が使われるシステムにおける何らかの依存関係を" +"記述する文字列です。このフィールドは、ダウンストリームプロジェクトの維持管理" +"担当者向けにヒントを提供することを意図しており、 ``distutils`` 配布物にとって" +"は何ら意味を持ちません。" -#: ../source/specifications/dependency-specifiers.rst:256 -msgid ":py:func:`platform.version()`" -msgstr ":py:func:`platform.version()`" +#: ../source/specifications/core-metadata.rst:579 +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/dependency-specifiers.rst:257 +#: ../source/specifications/core-metadata.rst:585 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``" +"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:" +"`Version specifier specification `: they should " +"correspond to the version scheme used by the external dependency." 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``" +"それらは非 Python のソフトウェアリリースを参照するものですので、このフィール" +"ドでのバージョン番号は :ref:`バージョン指定子仕様 ` で指" +"定されたフォーマットに適合することを **要求されていません** : それらは、外部" +"依存関係によって使われるバージョンスキームに対応するべきです。" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``python_version``" -msgstr "``python_version``" +#: ../source/specifications/core-metadata.rst:590 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "使用される文字列に対して特に規則がないという点に注意してください。" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" -msgstr "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/core-metadata.rst:602 +msgid "Project-URL (multiple-use)" +msgstr "Project-URL (複数回の使用可)" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``3.4``, ``2.7``" -msgstr "``3.4``, ``2.7``" +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" +"そのプロジェクトの閲覧可能な URL とラベルを含む文字列をコンマで区切ったもの。" -#: ../source/specifications/dependency-specifiers.rst:263 -msgid "``python_full_version``" -msgstr "``python_full_version``" +#: ../source/specifications/core-metadata.rst:613 +msgid "The label is free text limited to 32 characters." +msgstr "このラベルは32 文字以内のフリーテキストです。" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid ":py:func:`platform.python_version()`" -msgstr ":py:func:`platform.python_version()`" +#: ../source/specifications/core-metadata.rst:621 +msgid "Provides-Extra (multiple use)" +msgstr "Provides-Extra (複数回の使用可)" -#: ../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/core-metadata.rst:624 +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 "" +"曖昧さ (すなわち正規化が要求されていない) を避けるために :pep:`685` で制限さ" +"れた正当な値を。古めのメタデータのバージョンでは、 ``Name:`` を伴う行で値に制" +"限が導入され、正規化規則も導入されました。" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``implementation_name``" -msgstr "``implementation_name``" +#: ../source/specifications/core-metadata.rst:629 +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 " +"and end with a letter or number. Hyphens cannot be followed by another " +"hyphen. Names are limited to those which match the following regex (which " +"guarantees unambiguity)::" +msgstr "" +"追加的な機能の名前を含む文字列。正当な名前は、 ASCII 小文字・ ASCII 数字・ハ" +"イフンからのみ構成されます。先頭と末尾は文字か数字でなければなりません。ハイ" +"フンは連続してはいけません。名前は次の正規表現にマッチしなければなりません " +"(そうすることで曖昧さを排除します)::" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid ":py:data:`sys.implementation.name `" -msgstr ":py:data:`sys.implementation.name `" +#: ../source/specifications/core-metadata.rst:637 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" +"指定された名前は、追加的な機能が要求されたか否かに応じて依存関係を構築するた" +"めに使われます。" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "``cpython``" -msgstr "``cpython``" +#: ../source/specifications/core-metadata.rst:645 +msgid "" +"A second distribution requires an optional dependency by placing it inside " +"square brackets, and can request multiple features by separating them with a " +"comma (,). The requirements are evaluated for each requested feature and " +"added to the set of requirements for the distribution." +msgstr "" +"２番目の配布物は、角括弧の中に書くことで追加の依存先を要求し、コンマ (,) で区" +"切ることで複数の機能を要求することができます。要求事項は、要求されたそれぞれ" +"の機能について評価され、配布物の要求する依存関係の組に追加されます。" -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``implementation_version``" -msgstr "``implementation_version``" +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" +"``test`` と ``doc`` という二つの名前は、順に自動化されたテストと説明文書の生" +"成のために必要な依存先として予約されています。" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "see definition below" -msgstr "下方の定義を見てください" +#: ../source/specifications/core-metadata.rst:659 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" +"``Requires-Diet:`` のどこからも参照されていなくても、 ``Provides-Extra:`` を" +"指定しても構いません。" -#: ../source/specifications/dependency-specifiers.rst:272 -msgid "``extra``" -msgstr "``extra``" +#: ../source/specifications/core-metadata.rst:662 +msgid "" +"When writing data for older metadata versions, names MUST be normalized " +"following the same rules used for the ``Name:`` field when performing " +"comparisons. Tools writing metadata MUST raise an error if two ``Provides-" +"Extra:`` entries would clash after being normalized." +msgstr "" +"古めのメタデータのバージョンでデータを書く時、比較を行う時には ``Name:`` " +"フィールドに使われるのと同じ規則に従って正規化されなければなりません。ふたつ" +"の ``Provides-Extra:`` エントリが正規化後に衝突する場合には、メタデータを書き" +"込むツールはエラーを発生させなければなりません。" -#: ../source/specifications/dependency-specifiers.rst:273 +#: ../source/specifications/core-metadata.rst:667 msgid "" -"An error except when defined by the context interpreting the specification." -msgstr "仕様を通訳する文脈で定義された場合を除くエラー。" +"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 " +"would be invalid following the rules for ``Name:`` in any core metadata " +"version, the user SHOULD be warned and the value ignored to avoid ambiguity. " +"Tools MAY choose to raise an error when reading an invalid name for older " +"metadata versions." +msgstr "" +"メタデータの古めのバージョンから読み込む時、このフィールドの値が新しめのメタ" +"データバージョンとして正当でない場合にツールが警告するべきです。コアとなるメ" +"タデータのバージョンで ``Name:`` に対する規則に照らして値が正当ではないとすれ" +"ばユーザは警告されるべきで、その値は曖昧さを避けるために無視されるべきです。" +"古めのメタデータバージョンとして不当な名前を読み取った場合には、ツールはエ" +"ラーを発出することを選択しても構いません。" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "``test``" -msgstr "``test``" +#: ../source/specifications/core-metadata.rst:675 +msgid "Rarely Used Fields" +msgstr "稀に使われるフィールド" -#: ../source/specifications/dependency-specifiers.rst:277 +#: ../source/specifications/core-metadata.rst:677 msgid "" -"The ``implementation_version`` marker variable is derived from :py:data:`sys." -"implementation.version `:" +"The fields in this section are currently rarely used, as their design was " +"inspired by comparable mechanisms in Linux package management systems, and " +"it isn't at all clear how tools should interpret them in the context of an " +"open index server such as `PyPI `__." msgstr "" -"``implementation_version`` マーカ変数は、 :py:data:`sys.implementation." -"version ` から派生したものです :" +"この節のフィールドは、 Linux のパッケージ管理システムにおける類似の機構に触発" +"されて設計されましたが、 `PyPI `__ のような開放的なインデッ" +"クスサーバの文脈でツールがどのように翻案するべきかが全く明らかではないので、" +"現在ではほとんど使われません。" -#: ../source/specifications/dependency-specifiers.rst:294 +#: ../source/specifications/core-metadata.rst:682 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"As a result, popular installation tools ignore them completely, which in " +"turn means there is little incentive for package publishers to set them " +"appropriately. However, they're retained in the metadata specification, as " +"they're still potentially useful for informational purposes, and can also be " +"used for their originally intended purpose in combination with a curated " +"package repository." msgstr "" -"この環境マーカの節は、当初は :pep:`508` を通して定義されましたが、 :pep:" -"`345` における環境マーカの節を置き換えます。" - -#: ../source/specifications/dependency-specifiers.rst:298 -msgid "Complete Grammar" -msgstr "完全な文法" +"その結果として、人気のあるインストールツールでは完全に無視されていて、そのた" +"めに今度はパッケージを公開する側でもこれらのフィールドを適切に設定しておく誘" +"因がほとんどなくなっています。しかしながら、これらのフィールドは、情報提供の" +"目的ではまだ潜在的に役に立つことと、細かく注釈をつけるようなパッケージリポジ" +"トリと組み合わせれば本来意図された目的に用いることができることから、メタデー" +"タの仕様には残されています。" -#: ../source/specifications/dependency-specifiers.rst:300 -msgid "The complete parsley grammar::" -msgstr "完全な parsley 文法::" +#: ../source/specifications/core-metadata.rst:692 +msgid "Provides-Dist (multiple use)" +msgstr "Provides-Dist (複数回の使用可)" -#: ../source/specifications/dependency-specifiers.rst:407 -msgid "A test program - if the grammar is in a string ``grammar``:" -msgstr "テストプログラム - もし ``grammar`` 文字列内に文法があれば:" +#: ../source/specifications/core-metadata.rst:699 +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 "" +"それぞれのエントリは、この配布物に含まれている Distutils プロジェクトの名前を" +"文字列で含みます。このフィールドは、プロジェクトを特定する ``Name`` フィール" +"ドと後続するバージョンを *含んでいなければなりません*: Name (Version) 。" -#: ../source/specifications/dependency-specifiers.rst:478 -msgid "November 2015: This specification was approved through :pep:`508`." -msgstr "2015年11月: :pep:`508` を通じてこの仕様が承認されました。" +#: ../source/specifications/core-metadata.rst:704 +msgid "" +"A distribution may provide additional names, e.g. to indicate that multiple " +"projects have been bundled together. For instance, source distributions of " +"the ``ZODB`` project have historically included the ``transaction`` project, " +"which is now available as a separate distribution. Installing such a source " +"distribution satisfies requirements for both ``ZODB`` and ``transaction``." +msgstr "" +"配布物は、複数のプロジェクトが一緒に束ねられている場合には、それを示す追加の" +"名前を持っていても構いません。例えば、 ``ZODB`` プロジェクトのソースコード配" +"布物は、歴史的に ``transaction`` プロジェクトを包含していましたが、今では個別" +"の配布物として利用可能です。そのようなソースコード配布物をインストールする" +"と、 ``ZODB`` と ``transaction`` の両方の要求事項を満たします。" -#: ../source/specifications/dependency-specifiers.rst:479 +#: ../source/specifications/core-metadata.rst:711 msgid "" -"July 2019: 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]_" +"A distribution may also provide a \"virtual\" project name, which does not " +"correspond to any separately-distributed project: such a name might be used " +"to indicate an abstract capability which could be supplied by one of " +"multiple projects. E.g., multiple projects might supply RDBMS bindings for " +"use by a given ORM: each project might declare that it provides ``ORM-" +"bindings``, allowing other projects to depend only on having at most one of " +"them installed." msgstr "" -"2019年6月: ``python_version`` の定義は、Python の将来のバージョンが二桁のメ" -"ジャーバージョンやマイナーバージョンを持つ場合 (例えば 3.10) でもそれを収容で" -"きるように、 ``platform.python_version()[:3]`` から ``'.'.join(platform." -"python_version_tuple()[:2])`` へ `変更されました `_ 。 [#future_versions]_" +"配布物は、また、個別に配布されているどんなプロジェクトにも紐付かない \"仮想の" +"\" プロジェクト名を持っていても構いません: そのような名前は、複数のプロジェク" +"トのうちのひとつで供給される抽象的な能力を示すために使われるかもしれません。" +"例えば、複数のプロジェクトがとある ORM で使われる RDBMS バインディングを提供" +"していても構いません: それぞれのプロジェクトが、他のプロジェクトが依存する時" +"にはそのうちの高々１個だけがインストールされていれば十分な ``ORM-bindings`` " +"を提供すると宣言していても構わないのです。" -#: ../source/specifications/dependency-specifiers.rst:489 +#: ../source/specifications/core-metadata.rst:719 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"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 "" -"Python のパッケージをインストールする際に推奨されるツールである pip (http://" -"pip.readthedocs.org/en/stable/)" +"バージョンの宣言があっても構いませんが、 :doc:`バージョン指定子 ` に記述された規則に従ったものでなければなりません。もし指定されて" +"いなければ、配布物のバージョン番号が暗黙理に使われます。" -#: ../source/specifications/dependency-specifiers.rst:492 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" -msgstr "parsley PEG ライブラリ。 (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/core-metadata.rst:734 +msgid "Obsoletes-Dist (multiple use)" +msgstr "Obsoletes-Dist (複数回の使用可)" -#: ../source/specifications/dependency-specifiers.rst:495 +#: ../source/specifications/core-metadata.rst:741 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"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 "" -"Python の将来のバージョンでは、環境マーカ変数の ``python_version`` の定義が問" -"題をはらむかもしれません。 (https://github.com/python/peps/issues/560)" +"それぞれのエントリは、この配布物が出たことで旧式化した、従ってこれらふたつの" +"プロジェクトが同時にインストールされるべきではない distutils プロジェクトの配" +"布物を記述する文字列を含みます。" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" -msgstr "インストールされた配布物の配布元へ直接アクセスする URL を記録する" +#: ../source/specifications/core-metadata.rst:745 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" +"バージョンの宣言があっても構いません。バージョン番号は :doc:`バージョン指定" +"子 ` で指定されたフォーマットでなければなりません。" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/core-metadata.rst:750 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 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 "" -"この説明文書では、インストール済みの配布物の `*.dist-info` ディレクトリにあ" -"る :file:`direct_url.json` ファイルによって配布物の配布元へ直接アクセスする " -"URL を記録する方法を指定します。 ``*.dist-info`` ディレクトリの一般的な構造と" -"使用方法は、 :ref:`インストール済みパッケージを記録する ` に記述されています。" +"このフィールドの最もよくある使い方は、例えば Gorgon 2.3 が Torqued Python " +"1.0 の一部として組み込まれた時のように、プロジェクトの名前が変更された場合で" +"しょう。 Torqued Python をインストールするなら、 Gorgon 配布物は削除されるべ" +"きです。" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/core-metadata.rst:763 +msgid "Deprecated Fields" +msgstr "非推奨となったフィールド" + +#: ../source/specifications/core-metadata.rst:766 +msgid "Requires" +msgstr "要求事項" + +#: ../source/specifications/core-metadata.rst:769 +msgid "in favour of ``Requires-Dist``" +msgstr "``Requires-Dist`` に従って" + +#: ../source/specifications/core-metadata.rst:772 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)." +"Each entry contains a string describing some other module or package " +"required by this package." msgstr "" -":file:`direct_url.json` ファイルは、要求事項が指定するダイレクト (VCS の URL " -"を含む) 参照 URL からインストールしている時に、インストーラによって :file:`*." -"dist-info` ディレクトリに生成されなければなりません。" +"それぞれのエントリは、このパッケージが必要とする他のモジュールやパッケージを" +"記述した文字列を含みます。" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/core-metadata.rst:775 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"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 "" -"他のタイプの要求事項 (すなわち、名前とバージョン指定子) から配布物をインス" -"トールする際には、このファイルを生成してはなりません。" +"要求事項の文字列のフォーマットは、 ``import`` ステートメントで使うことができ" +"るモジュールやパッケージの名前のフォーマットと同一のもので、オプションとして" +"カッコ内に入れたバージョン宣言を伴うことがあります。" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/core-metadata.rst:779 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"A version declaration is a series of conditional operators and version " +"numbers, separated by commas. Conditional operators must be one of \"<\", " +"\">\"', \"<=\", \">=\", \"==\", and \"!=\". Version numbers must be in the " +"format accepted by the ``distutils.version.StrictVersion`` class: two or " +"three dot-separated numeric components, with an optional \"pre-release\" tag " +"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 "" -"この JSON ファイルは、 :rfc:`8259` に準拠するように UTF-8 で符号化されていな" -"ければならず、シリアル化の方法は :doc:`direct-url-data-structure` でなければ" -"なりません。" +"バージョン宣言は、一連の比較演算子とバージョン番号をカンマで区切ったもので" +"す。比較演算子は、\"<\", \">\", \"<=\", \">=\", \"==\", \"!=\" のいずれかひと" +"つでなければなりません。バージョン番号は、オプションとして 'a' か 'b' の後ろ" +"に数字が続く形の \"pre-release\" タグを末尾につけた、二つか三つの数字部分を" +"ドットで区切ったものです。バージョン番号の例としては、 \"1.0\" や \"2.3a2\" " +"や \"1.3.99\" 、" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/core-metadata.rst:787 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`." +"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 "" -"要求された URL が file:// スキームであって VCS からチェックアウトしたものを含" -"むローカルディレクトリを指し示している場合には、インストーラはいかなる VCS 情" -"報をも推定してはならず、従って、いかなる (``vcs_info`` のような) VCS 関連情報" -"をも :file:`direct_url.json` に出力してはなりません。" +"例えば \">1.0, !=1.3.4, <2.0\" という文字列が正当なバージョン宣言であるよう" +"に、比較演算子はいくつでも指定することができます。" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/core-metadata.rst:790 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``." +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." msgstr "" -"一般的な規則として、 :file:`direct_url.json` を生成する際には、インストーラは" -"可能な限り要求された URL に含まれる情報を保存するべきです。例えば、 user:" -"password を環境変数から読み込むなら環境変数を参照するような URL として保存さ" -"れるべきであり、 ``requested_revision`` は要求された URL の中に出現するものを" -"極力そのまま反映するべきです。しかしながら、この情報は (``commit_id`` のよう" -"な) もっと精密なデータを使って *精製* されます。" +"次に示すすべての要求仕様文字列 は実際に可能なものです: " +"\"rfc822\", \"zlib (>=1.1.4)\", \"zope\"。" + +#: ../source/specifications/core-metadata.rst:793 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" +"どのような文字列が用いられるべきであるかについては、公式に認められたリストは" +"ありません; 独自の標準を選択することが Python コミュニティに委ねられていま" +"す。" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" -msgstr "pip コマンドの例と direct_url.json に与える影響" +#: ../source/specifications/core-metadata.rst:806 +msgid "Provides" +msgstr "提供する" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" -msgstr "``direct_url.json`` を生成するコマンド:" +#: ../source/specifications/core-metadata.rst:809 +msgid "in favour of ``Provides-Dist``" +msgstr "``Provides-Dist`` を支持して " -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/core-metadata.rst:812 +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 " +"the ones used in Requirements fields. A version declaration may be supplied " +"(without a comparison operator); the package’s version number will be " +"implied if none is specified." msgstr "" +"それぞれのエントリには、そのパッケージをインストールすると提供されるであろう" +"パッケージなりモジュールなりについて記述した文字列を含みます。このような文字" +"列は、Requirements フィールドで使われるものに合致しているべきです。 (比較演算" +"子なしなら) バージョン宣言もあっても構いません; もしバージョン宣言がなけれ" +"ば、そのパッケージのバージョン番号を援用します。" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/core-metadata.rst:828 +msgid "Obsoletes" +msgstr "古くなった " + +#: ../source/specifications/core-metadata.rst:831 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "``Obsoletes-Dist`` に従って" + +#: ../source/specifications/core-metadata.rst:834 +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/direct-url.rst:51 +#: ../source/specifications/core-metadata.rst:838 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"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 "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"このフィールドの最もよくある使い方は、例えば Gorgon 2.3 が Torqued Python " +"1.0 の一部として組み込まれた時のように、プロジェクトの名前が変更された場合で" +"しょう。 Torqued Python をインストールするなら、 Gorgon パッケージは削除され" +"るべきです。" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/core-metadata.rst:850 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." msgstr "" +"2001年3月: :pep:`241` を通じてコアとなるメタデータ 1.0 が承認されました。" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/core-metadata.rst:851 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`:" msgstr "" +"2003年4月: :pep:`314` を通じてコアとなるメタデータ 1.1 が承認されました:" -#: ../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)" +#: ../source/specifications/core-metadata.rst:852 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." msgstr "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (この場合、 ``url`` は git リポジトリのクローン先" -"のローカルディレクトリになり、 ``dir_info`` は ``\"editable\": true`` という" -"形で存在し、 ``vcs_info`` は設定されないということになるでしょう)" +"2010年2月: :pep:`345` を通じてコアとなるメタデータ 1.2 が承認されました。" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/core-metadata.rst:853 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." msgstr "" +"2018年2月: :pep:`566` を通じてコアとなるメタデータ 2.1 が承認されました。" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" -msgstr "``direct_url.json`` を *生成しない* コマンド" +#: ../source/specifications/core-metadata.rst:855 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "``Description-Content-Type`` と ``Provides-Extra`` を追加しました。" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/core-metadata.rst:856 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "メタデータを JSON に変換する正規化された方法を追加しました。" + +#: ../source/specifications/core-metadata.rst:857 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "``Name`` フィールドの文法に制限を加えました。" + +#: ../source/specifications/core-metadata.rst:859 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." msgstr "" +"2020年10月: :pep:`643` を通じてコアとなるメタデータ 2.2 が承認されました。" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/core-metadata.rst:861 +msgid "Added the ``Dynamic`` field." +msgstr "``Dynamic`` フィールドを追加しました。" + +#: ../source/specifications/core-metadata.rst:863 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." msgstr "" +"2022年3月: :pep:`685` を通じてコアとなるメタデータ 2.3 が承認されました。" -#: ../source/specifications/direct-url.rst:69 -msgid "March 2020: This specification was approved through :pep:`610`." -msgstr "2020年3月: :pep:`610` を通じてこの仕様が承認されました。" +#: ../source/specifications/core-metadata.rst:865 +msgid "Restricted extra names to be normalized." +msgstr "その他の名称 の標準化に制限を加えました。" -#: ../source/specifications/direct-url-data-structure.rst:7 -msgid "Direct URL Data Structure" -msgstr "ダイレクト URL データ構造 " +#: ../source/specifications/core-metadata.rst:869 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "reStructuredText マークアップ言語: https://docutils.sourceforge.io/" -#: ../source/specifications/direct-url-data-structure.rst:9 +#: ../source/specifications/core-metadata.rst:874 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "RFC 822 長形式ヘッダフィールド: :rfc:`822#section-3.1.1`" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "依存関係指定子" + +#: ../source/specifications/dependency-specifiers.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." +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -"この説明文書では、python プロジェクトや VCS 上のソースツリーやローカルのソー" -"スツリーやソースコード配布物や wheel ファイルのような配布物アーティファクトに" -"対してURLを表現することを可能とする、 JSON のシリアル化抽象データ構造の仕様を" -"定義します。" +"元々は :pep:`508` で指定されていた依存関係指定子のフォーマットを、この説明文" +"書は記述します。" -#: ../source/specifications/direct-url-data-structure.rst:13 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"At time of writing, it is not formally specified how to merge the parts of " -"this data structure into a single URL that can be passed to tools. A common " -"representation is the pip URL format (`VCS Support `_), " -"other examples are provided in 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 "" -"本稿執筆時点では、ツール群に渡せるようにこのデータ構造の各部分を単一の URL に" -"まとめる方法については公式には指定されていません。よく見られる表現形式は pip " -"URL フォーマット (`VCS サポート `_) で、他の例が :ref:`バー" -"ジョン指定子仕様 ` の中で提供されています。" +"依存関係 の任務は、 pip [#pip]_ のようなツールがインストールする" +"べき正しいパッケージを探し出すことができるようにすることです。これは時には大" +"変に曖昧で名称を指定するだけであったり、別の時には非常に限定的でインストール" +"するべき特定のファイルを参照したりします。場合によっては、依存関係 " +" がひとつのプラットフォームでのみ妥当であったり、いくつかのバー" +"ジョンだけが受け入れ可能であったりするので、(依存関係 を記述す" +"る) 言語としてはこれらすべてのケースを記述できるものでなければなりません。" -#: ../source/specifications/direct-url-data-structure.rst:21 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"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 "" -"直接 URL データ構造は辞書でなければならず、 :rfc:`8259` に従って JSON にシリ" -"アライズできなければなりません。" +"定義された言語は、簡潔な行単位のフォーマットであって pip の requirements ファ" +"イルで既に広く使われているものですが、そのようなファイル群を許容するようなコ" +"マンドラインオプションを指定することはしていません。ひとつ注意しなければなら" +"ないのは、 :ref:`バージョン指定子仕様 ` で指定されている" +"ような URL を参照する形式は実は pip では実装されていないのに、現在の pip の本" +"来のフォーマットよりもむしろそちらのフォーマットを使っているという点です。" -#: ../source/specifications/direct-url-data-structure.rst:24 +#: ../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:11 +msgid "Specification" +msgstr "仕様" + +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" +msgstr "この言語のすべての機能を、名前に基づいた参照とともに示します::" + +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" +msgstr "最低限の URL に基づいた参照::" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "概念" + +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Its content must be a valid URL according to the `WHATWG URL " -"Standard `_." +"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 "" -"少なくとも二つのフィールドが含まれていなければなりません。一つ目は " -"``string`` 型の ``url`` です。その内容は、 `WHATWG URL 標準 `_ に従う正当な URL でなければなりません。" +"依存関係の指定では、常に、配布物の名前を指定します。名前で指定された配布物で" +"特定の追加機能を有効にするように依存関係を拡張するような追加物 を含ん" +"でいても構いません。インストールされたバージョンをバージョンリミットで制御す" +"ることもできますし、特定のアーティファクトをインストールするために URL を与え" +"ることもできます。依存関係は最終的に環境マーカを用いて条件別に作成することも" +"できます。" -#: ../source/specifications/direct-url-data-structure.rst:28 +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "文法" + +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"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 archive 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." +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -"``url`` が何を参照しているかによって、二つ目のフィールドは ``vcs_info`` " -"(``url`` が VCS 参照である場合)・ ``archive_info`` (``url`` がソースコード" -"アーカイブか wheel である場合)・ ``dir_info`` (``url`` がローカルディレクトリ" -"である場合) のうちのいずれか一つでなければなりません。これらの info フィール" -"ドは、(空である場合もありますが) 以下に定義するキー群を持つことができるサブ" -"ディレクトリを値として持ちます。" +"最初に文法について簡単に触れた後、それぞれの節の意味論 について深" +"く掘り下げることにしましょう。" -#: ../source/specifications/direct-url-data-structure.rst:34 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"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 "" -"固持する場合には、``url`` は、セキュリティ上の理由から、機微に関わる認証情報" -"をすべて削除しておかなければなりません。" +"配布物の仕様は ASCII テキストで書かれています。厳密な文法としては parsley " +"[#parsley]_ の文法を使っています。この仕様は、コメントや継続による複数行サ" +"ポートやその他の機能の枠組みを与えるもっと大きなシステムの中に組み込まれるこ" +"とを期待しています。" -#: ../source/specifications/direct-url-data-structure.rst:37 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression:" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -"URLの user:password の部分は、しかしながら、次に述べる正規表現に合致する形" -"で、環境変数から構成しても構いません:" +"役に立つ構文解析ツリーを構成するための注釈機能を含む完全な文法は、この説明文" +"書の末尾に置きました。" -#: ../source/specifications/direct-url-data-structure.rst:45 +#: ../source/specifications/dependency-specifiers.rst:62 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``." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -"さらに、 URL の user:password 部分は、広く知られたセキュリティ的に問題のない" -"文字列であっても構いません。典型的な例としては、 ``ssh://git@gitlab.com/user/" -"repo`` のような URL における ``git`` を挙げることができます。" - -#: ../source/specifications/direct-url-data-structure.rst:50 -msgid "VCS URLs" -msgstr "VCS URL群" +":ref:`バージョン指定子仕様 ` の規則に従ってバージョンを指" +"定しても構いません。(ノート: URI は :rfc:`std-66 <3986>` で定義されていま" +"す)::" -#: ../source/specifications/direct-url-data-structure.rst:52 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -"``url`` が VCS リポジトリを参照している場合、 以下のキー群を伴った " -"``vcs_info`` キーが辞書に存在していなければなりません:" +"環境マーカを使うことで、ある仕様が特定の環境でのみ有効であることを示すことが" +"できます::" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/dependency-specifiers.rst:102 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." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -"(``git`` ・ ``hg`` ・ ``bzr`` ・ ``svn`` のいずれかのような) VCS の名前を含ん" -"だ ``vcs`` キー (``string`` 型) が存在していなければなりません。その他の VCS " -"については、この仕様を修正するための PEP を書くことによって登録されるべきで" -"す。当該 VCS の checkout/download コマンドへの翻訳をしなくてもインストーラが " -"手を離してしまえるようにするために、 ``url`` の値は対応する VCS と齟齬のない" -"ものでなければなりません。" +"配布物のうちの必須ではない部分については extras フィールドを使って指定するこ" +"とができます::" -#: ../source/specifications/direct-url-data-structure.rst:61 +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "追加物の名前に対する制限事項は :pep:`685` で定義されています。" + +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" +msgstr "私たちに名前に基づいた要求仕様を与えてください::" + +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" +msgstr "そして、直接参照に用いる要求仕様のための規則はこちら::" + +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" +msgstr "依存関係を指定することができる統一規則への案内はこちら::" + +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" +msgstr "空白文字 " + +#: ../source/specifications/dependency-specifiers.rst:128 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)." +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -"``requested_revision`` キー (``string`` 型) は、ブランチ・タグ・リファレン" -"ス・コミット・リビジョンその他を指定するために存在していても構いません (VCS " -"と互換性を持つフォーマットにて)。" +"行を分割するものではない空白文字には特に意味はなく、ほとんどの場合には必須で" +"はないものです。唯一の例外は、 URL による要求事項の末尾を検出するためのもので" +"す。" + +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" +msgstr "名前 " -#: ../source/specifications/direct-url-data-structure.rst:63 +#: ../source/specifications/dependency-specifiers.rst:134 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." +"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 "" -"``commit_id`` キー (``string`` 型) は、正確にどのコミットまたはリビジョンがイ" -"ンストールされた/されるかを示すもので、必須のキーです。 VCS がリビジョン識別" -"子に基づくコミットハッシュをサポートしているなら、インストールされたものの" -"ソースコードの不変のバージョンを指し示す目的で、そのようなコミットハッシュを " -"``commit_id`` として使わなければなりません。" +"Python の配布物の名前は、現時点では :pep:`345` で定義されています。名前は配布" +"物の最も基本的な識別子として働きます。(名前は) あらゆる依存関係の指定に出現" +"し、それだけで十分に指定することができます。しかしながら、 PyPI では名前に厳" +"密な制約を課しています - 名前は大文字小文字を区別しない正規表現に合致しなけれ" +"ば受け入れられません。従って、この説明文書では、その正規表現に合致する識別子" +"だけを受け入れ可能な値として扱うことにしましょう。名前の完全な再定義はメタ" +"データ PEP として将来に出現するかもしれません。ここでいう (re.IGNORECASE とと" +"もに評価されるべき) 正規表現とは、次のようなものです::" -#: ../source/specifications/direct-url-data-structure.rst:71 -msgid "Archive URLs" -msgstr "アーカイブ URL 群" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" +msgstr "追加物 " -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/dependency-specifiers.rst:148 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:" +"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 "" -"``url`` がソースコードのアーカイブや wheel ファイルを指し示す場合には、 " -"``archive_info`` キーが次のようなキーを持つ辞書の形で存在しなければなりませ" -"ん:" +"追加物とは、配布物の必須ではない部分のことです。配布物では追加物を幾つでも指" +"定することができ、追加物が依存関係の指定場所で使われた **場合** には、それぞ" +"れの追加物が配布物の追加的な依存関係を宣言する結果になります。例えば::" -#: ../source/specifications/direct-url-data-structure.rst:76 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"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 "" -"``hashes`` キーは、ハッシュ名から16進数表記のファイルハッシュ値への対応を保持" -"する辞書として存在するべきです。" +"追加物 の依存関係の合併とは、その追加物が添付されている配布物 " +" の依存関係と一緒に定義されることです。上に示した例では、結果と" +"して requests がインストールされることになり、requests は自身の依存関係を持つ" +"ので requests の \"security\" 追加物 に列挙されたすべての依存関係 " +"(先) もインストールされることになります。" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/dependency-specifiers.rst:160 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)." +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -"複数のハッシュ値を含めることが可能で、そのような複数のハッシュ値を使って何を" -"するか (すべてのハッシュ値を検証しても一部だけを検証しても構いませんし、何も" -"しなくても構いません) については利用する側次第です。" +"複数の追加物 が列挙されている場合には、すべての依存関係の合併集合が依" +"存関係になります。" -#: ../source/specifications/direct-url-data-structure.rst:83 -msgid "These hash names SHOULD always be normalized to be lowercase." -msgstr "これらのハッシュの名前は、常に小文字に正規化されているべきです。" +#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/simple-repository-api.rst:888 +msgid "Versions" +msgstr "バージョン指定子" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Any hash algorithm available via :py:mod:`hashlib` (specifically any that " -"can be passed to :py:func:`hashlib.new()` and do not require additional " -"parameters) can be used as a key for the hashes dictionary. At least one " -"secure algorithm from :py:data:`hashlib.algorithms_guaranteed` SHOULD always " -"be included. At time of writing, ``sha256`` specifically is recommended." +"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 "" -":py:mod:`hash lib` 経由で利用可能なハッシュアルゴリズム (とりわけ、 :py:func:" -"`hashlib.new()` に渡すことができて、かつ、それ以上のパラメータを必要としない" -"もの) はどれでも、ハッシュ値を格納する辞書のキーとして用いることができま" -"す。 :py:data:`hashlib.algorithms_garanteed` から安全なアルゴリズムを少なくと" -"もひとつ選択して含めるべきです。執筆時点では、 ``sha256`` が特に推奨されてい" -"ます。" +"バージョン番号やその比較方法について、詳しくは :ref:`バージョン指定子仕様 " +"` をみてください。バージョン仕様は、配布物のバージョンと" +"して使うことができる範囲を定めています。これは、名前によって参照される配布物" +"にのみ適用されるのであって、URL を通じて指定されるものには該当しません。バー" +"ジョン番号の比較は、また、マーカー機能においても使われます。バージョンの周囲" +"にある必須でない括弧は :pep:`345` との互換性を保つために存在していますが、そ" +"のようなものを生成すべきではなくて受容するだけにとどめるべきです。" -#: ../source/specifications/direct-url-data-structure.rst:91 -msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." -msgstr "" -"非推奨となった ``hash`` キー (``string`` 型) は、後方互換性を保つ目的でなら " -"``=`` を値に取る形で存在していても構いません。" +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" +msgstr "環境マーカ" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/dependency-specifiers.rst:176 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." +"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 "" -"データ構造を生成する側では、ひとつまたは複数のハッシュが利用できるなら " -"``hashes`` キーを生成するべきです。以前からそうしていたので既存のクライアント" -"のために後方互換性を保つためなら、生成側は ``hash`` キーの生成を継続するべき" -"です。" +"環境マーカは、依存関係の指定においてその依存関係がいつ使われるべきであるかを" +"記述する規則を提供します。例えば、あるパッケージが argparse を必要とするとし" +"ましょう。Python 2.7 では argparse は常に存在します。もっと古いバージョンの " +"Python では依存関係としてインストールされなければなりません。これは次のように" +"表現することができます::" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/dependency-specifiers.rst:183 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." +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -"``hash`` と ``hashes`` の両方のキーが存在する時は、 ``hash`` キーの中に現れる" -"ハッシュは、 ``hashes`` の辞書の中にも存在しなければならず、そうすることで利" -"用する側では ``hashes`` キーがあればそれだけを考慮し、なければ ``hash`` に" -"フォールバックすることが可能になります。" - -#: ../source/specifications/direct-url-data-structure.rst:103 -msgid "Local directories" -msgstr "ローカルディレクトリ" +"マーカ表現は評価されると真か偽に帰着します。偽と評価された場合には、その依存" +"関係の指定は無視されなければなりません。" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"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 "" -"``url`` がローカルのディレクトリを参照している場合には、以下のキーを含む辞書" -"として ``dir_info`` キーが存在していなければなりません。" +"マーカ言語は Python そのものに触発されたもので、セキュリティ上の脆弱性になり" +"かねない任意コードの実行を伴わずに安全に評価を行うことができるので選ばれまし" +"た。マーカは:pep:`345` で初めて標準化されました。この説明文書では、 :pep:" +"`426` に記述されたデザインに見られるいくつかの問題点を修正しています。" -#: ../source/specifications/direct-url-data-structure.rst:108 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"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 "" -"配布物が編集可能モードでインストールされた/される場合には ``editable`` " -"(``boolean`` 型): ``true`` 、そうでなければ ``false`` 。存在していない場合の" -"デフォルトは ``false`` です。" +"マーカ表現の比較は比較演算子によって分類されます。 の中に入って" +"いない 演算子は、 Python における文字列でのそれと同様に動作しま" +"す。 演算子は、定義されている場合 (つまり両側に正当はバージョン" +"指定子を伴う場合) には、 :ref:`バージョン指定子仕様 ` の" +"バージョン比較規則を採用しています。演算子の動作がこの仕様で定義されておら" +"ず、かつ、その演算子が Python に存在する場合には、当該演算子は Python での動" +"作にフォールバックします。そうでない場合にはエラーを発生させるべきです。例え" +"ば、次の表現はエラーを発生させる結果となるでしょう::" -#: ../source/specifications/direct-url-data-structure.rst:111 +#: ../source/specifications/dependency-specifiers.rst:204 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." +"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 "" -"``url`` がローカルのディレクトリを参照している場合、 :rfc:``8089` に適合する " -"``file`` スキームが存在していなければなりません。特にパス部分は絶対パスでなけ" -"ればなりません。相対パスを絶対パスに変換する際には、シンボリックリンクはその" -"まま保存されているべきです。" - -#: ../source/specifications/direct-url-data-structure.rst:117 -msgid "Projects in subdirectories" -msgstr "サブディレクトリ内のプロジェクト群" +"ユーザ側から供給された定数は、常に ``'`` または ``\"`` なる引用記号を伴った文" +"字列として符号化されます。バックスラッシュによるエスケープは定義されていませ" +"んが、現存する実装ではサポートされているということを忘れないでください。この" +"仕様には (バックスラッシュエスケープは) 含まれていませんが、それは、複雑性を" +"増加させてしまうことと、現時点では目に見えるほどの必要性がないことが理由で" +"す。同様に、非 ASCII 文字のサポートも定義していません: 我々が参照するようなラ" +"ンタイムのすべての変数は、 ASCII 文字のみで構成されているものと期待されていま" +"す。" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/dependency-specifiers.rst:211 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 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 "" -"トップレベルの ``subdirectory`` フィールドは、 ``pyproject.toml`` または " -"``setup.py`` が存在する場所を指定するために、 VCS リポジトリやソースコードの" -"アーカイブやローカルのディレクトリのルートディレクトリに対する相対パスとして" -"示したディレクトリパスを値とするものとして存在することが許されています。" - -#: ../source/specifications/direct-url-data-structure.rst:124 -msgid "Registered VCS" -msgstr "登録済みの VCS" +"\"os_name\" のようなマーカの文法内の変数は、 Python のランタイム内でルック" +"アップすることで値へと解決されます。 \"extra\" を例外として、すべての値は現在" +"のすべてのバージョンの Python で定義されています - もし値が定義されていなけれ" +"ば、それはマーカの実装のエラーです。" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/dependency-specifiers.rst:216 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." +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -"この節では登録済み VCS; ``vcs`` や ``requested_revision`` やその他の " -"``vcs_info`` 内のフィールドや、さらにある場合には特定の VCS に特有のフィール" -"ドなどの使い方のような拡張された VCS 特有の情報 の一覧を示します。 PEP を書く" -"ことでこの仕様を修正する形で別の VCS を登録することが推奨されていますが、ツー" -"ルの側で他の VCS を (訳注、VCS 登録作業抜きで) サポートしても構いません。 " -"``vcs`` フィールドの値は、 (小文字の) コマンド名であるべきです。当該 VCS をサ" -"ポートするのに必要であると思われるその他のフィールドについては、当該 VCS のコ" -"マンド名で始まる名前にするべきです。" - -#: ../source/specifications/direct-url-data-structure.rst:136 -msgid "Git" -msgstr "Git" - -#: ../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 "Home page" -msgstr "ホームページ" - -#: ../source/specifications/direct-url-data-structure.rst:139 -msgid "https://git-scm.com/" -msgstr "https://git-scm.com/" - -#: ../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 command" -msgstr "vcs コマンド" - -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 -msgid "git" -msgstr "git" - -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "``vcs`` field" -msgstr "``vcs`` フィールド" - -#: ../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:212 -msgid "``requested_revision`` field" -msgstr "``requested_revision`` フィールド" +"未知の変数は、評価して真 か偽 となる比較の結果を返すのではな" +"く、エラーを生成しなければなりません。" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"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 "" -"タグ名・ブランチ名・Git 参照・コミットハッシュ・短縮型コミットハッシュ・その" -"他のコミットハッシュ的なもの。" - -#: ../source/specifications/direct-url-data-structure.rst:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 -msgid "``commit_id`` field" -msgstr "``commit_id`` フィールド" - -#: ../source/specifications/direct-url-data-structure.rst:152 -msgid "A commit hash (40 hexadecimal characters sha1)." -msgstr "コミットハッシュ (16進数で40文字のSHA1)。" +"特定の Python 実装で値を計算することができない変数は、バージョンについては " +"``0`` として、その他のすべての変数については空文字列として評価されるべきで" +"す。" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/dependency-specifiers.rst:223 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 \"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 "" -"ツールは、 ``requested_revision`` が Git 参照に対応しているか否かを判断するた" -"めに ``git show-ref`` や ``git symbolic-ref`` コマンドを使うことができます。" -"さらに、 ``refs/tags/`` で始まる参照はタグに対応し、クローンした後に ``refs/" -"remotes/origin/`` で始まる参照はブランチに対応します。" +"\"extra\" 変数は、扱いが特別です。それは wheel ファイルにおいて、その wheel " +"の ``METADATA`` ファイル内の特定の追加物 にどの仕様を適用するべきであ" +"るかを知らせるために使われますが、 ``METADATA`` ファイルの様式が :pep:`426` " +"のドラフトバージョンに基づいているので、現時点ではその仕様が存在していないの" +"です。それにも関わらず、この特別な扱いが行われる場所ではない文脈においては、 " +"\"extra\" 変数はその他の未知の変数と同様にエラーに帰着するべきです。" -#: ../source/specifications/direct-url-data-structure.rst:163 -msgid "Mercurial" -msgstr "Mercurial" +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" +msgstr "マーカ " -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" -msgstr "https://www.mercurial-scm.org/" +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" +msgstr "Python 同等物" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 -msgid "hg" -msgstr "hg" +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" +msgstr "値の例" -#: ../source/specifications/direct-url-data-structure.rst:175 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." -msgstr "タグ名・ブランチ名・チェンジセット ID ・短縮型チェンジセット ID。" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" +msgstr "``OS の名称 ``" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A changeset ID (40 hexadecimal characters)." -msgstr "チェンジセット ID (16 進数で 40 文字)。" +#: ../source/specifications/dependency-specifiers.rst:237 +msgid ":py:data:`os.name`" +msgstr ":py:data:`os.name`" -#: ../source/specifications/direct-url-data-structure.rst:181 -msgid "Bazaar" -msgstr "Bazaar" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" -#: ../source/specifications/direct-url-data-structure.rst:184 -msgid "https://www.breezy-vcs.org/" -msgstr "https://www.breezy-vcs.org/" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "``sys_platform``" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 -msgid "bzr" -msgstr "bzr" +#: ../source/specifications/dependency-specifiers.rst:240 +msgid ":py:data:`sys.platform`" +msgstr ":py:data:`sys.platform`" -#: ../source/specifications/direct-url-data-structure.rst:193 -msgid "A tag name, branch name, revision id." -msgstr "タグ名・ブランチ名・リビジョン id 。" +#: ../source/specifications/dependency-specifiers.rst:241 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (\"linux\" は Python3 か" +"ら、\"linux2\" は Python2 からであることに注意してください)" -#: ../source/specifications/direct-url-data-structure.rst:196 -msgid "A revision id." -msgstr "リビジョン id 。" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" +msgstr "``platform_machine``" -#: ../source/specifications/direct-url-data-structure.rst:199 -msgid "Subversion" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid ":py:func:`platform.machine()`" +msgstr ":py:func:`platform.machine()`" -#: ../source/specifications/direct-url-data-structure.rst:202 -msgid "https://subversion.apache.org/" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" +msgstr "``x86_64``" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "svn" -msgstr "svn" +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" +msgstr "``platform_python_implementation``" -#: ../source/specifications/direct-url-data-structure.rst:211 -msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." -msgstr "" -"``requested_revision`` は、 ``svn checkout`` ``--revision`` オプションと互換" -"でなければなりません。 Subversion では、ブランチまたはタグは ``url`` の一部で" -"す。" +#: ../source/specifications/dependency-specifiers.rst:247 +msgid ":py:func:`platform.python_implementation()`" +msgstr ":py:func:`platform.python_implementation()`" -#: ../source/specifications/direct-url-data-structure.rst:215 -msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." -msgstr "" -"Subversion は大域的にユニークな識別子をサポートしていないので、このフィールド" -"は当該リポジトリにおける Subversion のリビジョン番号です。" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" +msgstr "``CPython``, ``Jython``" -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "JSON Schema" -msgstr "JSON スキーマ" +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" +msgstr "``platform_release``" -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "" -"The following JSON Schema can be used to validate the contents of " -"``direct_url.json``:" -msgstr "" -"以下に述べる JSON スキーマを ``direct_url.json`` の内容を検証するために使うこ" -"とができます:" +#: ../source/specifications/dependency-specifiers.rst:250 +msgid ":py:func:`platform.release()`" +msgstr ":py:func:`platform.release()`" -#: ../source/specifications/direct-url-data-structure.rst:344 -msgid "Source archive:" -msgstr "ソースコードアーカイブ:" +#: ../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/direct-url-data-structure.rst:357 -msgid "Git URL with tag and commit-hash:" -msgstr "タグおよびコミットハッシュ付きの Git のURL:" +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" +msgstr "``platform_system``" -#: ../source/specifications/direct-url-data-structure.rst:370 -msgid "Local directory:" -msgstr "ローカルディレクトリ:" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid ":py:func:`platform.system()`" +msgstr ":py:func:`platform.system()`" -#: ../source/specifications/direct-url-data-structure.rst:379 -msgid "Local directory in editable mode:" -msgstr "編集可能モード状態にあるローカルディレクトリ:" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "``Linux``, ``Windows``, ``Java``" -#: ../source/specifications/direct-url-data-structure.rst:394 -msgid "" -"March 2020: This specification was approved through :pep:`610`, defining the " -"``direct_url.json`` metadata file." -msgstr "" -"2020年3月: ``direct_url.json`` メタデータファイルを定義するこの仕様は、 :pep:" -"`610` を通じて承認されました。" +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "``platform_version``" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:func:`platform.version()`" +msgstr ":py:func:`platform.version()`" + +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +"``#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 "" -"2023年1月: ``archive_info.hashes`` キーを追加しました (`議論 `_) 。" +"``#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/entry-points.rst:5 -msgid "Entry points specification" -msgstr "エントリポイントの仕様" +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" +msgstr "``python_version``" -#: ../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:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "``'.'.join(platform.python_version_tuple()[:2])``" -#: ../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." -msgstr "" -"配布物では、それぞれが関数を参照するような ``console_scripts`` エントリポイン" -"トを指定することができます。 *pip* (または console_scripts を認識する他のイン" -"ストーラ) が配布物をインストールする際に、各エントリポイントのコマンドライン" -"ラッパを生成します。" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" +msgstr "``3.4``, ``2.7``" -#: ../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 "" -"アプリケーションは、プラグインをロードするためにエントリポイントを用いること" -"ができます; 例えば、 Pygments (シンタックスハイライトを行うツール) は追加的な" -"字句解析器を使うことが可能であり、また、別にインストールされたパッケージから" -"提供されるスタイルを使うことができます。この件の詳細については、 :doc:`/" -"guides/creating-and-discovering-plugins` を見てください。" +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" +msgstr "``python_full_version``" -#: ../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 :py:mod:`importlib.metadata`. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"``setuptools`` to publish :py:mod:`importlib.metadata` compatible entry " -"point metadata, and runtime libraries other than :py:mod:`importlib." -"metadata` to portably read published entry point metadata (potentially with " -"different caching and conflict resolution strategies)." -msgstr "" -"エントリポイントのファイルフォーマットは、元々は、 setuptools でビルドされた" -"パッケージが、動作時 (ランタイム) に :py:mod:`importlib.metadata` で読み取ら" -"れるであろうと思われるインテグレーションポイントメタデータを提供できるように" -"と開発されました。現在では、 ``setuptools`` 以外のビルドツールが :py:mod:" -"`importlib.metadata` と互換性のあるエントリポイントのメタデータを公開し、 :" -"py:mod:`importlib.metadata` 以外のランタイムライブラリが移植可能な形で公開さ" -"れているエントリポイントのメタデータを (潜在的には、たとえ異なるキャッシング" -"と衝突回避の戦略を採用していたとしても) 読み取ることができるようにと PyPA 相" -"互互換性仕様において定義されています。" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid ":py:func:`platform.python_version()`" +msgstr ":py:func:`platform.python_version()`" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" -msgstr "データモデル" +#: ../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/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" -msgstr "" -"概念的に、エントリポイントは３個の属性を持たなければならないと定義されていま" -"す:" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" +msgstr "``implementation_name``" -#: ../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 "" -"エントリポイントが属する *group* は、それがどのような種類のオブジェクトを提供" -"するのかを示します。例えば、 ``console_scripts`` グループはコマンドとして使え" -"る関数を参照するエントリポイント用であり、一方、 ``pygments.styles`` は " -"pygments スタイルを定義するクラスを提供するグループです。利用する側 (コン" -"シューマ) は、通常、期待するインタフェースを定義しています。衝突を避けるため" -"に、新しいグループを定義するのであればコンシューマは自身の PyPI での名前の後" -"に ``.`` を後置したもので始まるグループ名を使うべきです。グループ名は、ひとつ" -"かそれ以上の文字・数字・アンダースコアをドット文字で区切ったもの (正規表現で " -"``^\\w+(\\.\\w)*$``) でなければなりません。" +#: ../source/specifications/dependency-specifiers.rst:267 +msgid ":py:data:`sys.implementation.name `" +msgstr ":py:data:`sys.implementation.name `" -#: ../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 "" -"グループ内では、エントリポイントを **name** で識別します。このことの正確な意" -"味は利用する側次第です。コンソールスクリプトでは、エントリポイントの名前はそ" -"のコマンドを起動するのに使われる名前です。配布物の内部では、エントリポイント" -"の名前は一意に決まるべきです。別の配布物が同じ名前を提供する場合には、利用す" -"る側でそのような衝突をどのように扱うのかを決めます。名前は ``=`` を除いてどん" -"な文字を含んでいても構いませんが、空白文字で始まったり終わったりすることはで" -"きず、 ``[`` で始まることもできません。エントリポイントをこれから作るのであれ" -"ば、文字・数字・アンダースコア・ドットとダッシュ (正規表現で言うと " -"``[\\w.-]+``) だけを用いることが推奨されています。" +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" +msgstr "``cpython``" -#: ../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/dependency-specifiers.rst:269 +msgid "``implementation_version``" +msgstr "``implementation_version``" -#: ../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:270 +msgid "see definition below" +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 "" -"さらに追加のプロパティがあります: **extras** は、エントリポイントを提供する配" -"布物の追加的な機能をを識別する１組みの文字列です。もし指定されていれば、その" -"ような 'extras' の依存関係をエントリポイントが要求しています。メタデータの" -"フィールド :ref:`metadata_provides_extra` を見てください。" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" +msgstr "``extra``" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/dependency-specifiers.rst:273 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 のような" -"もっと新しいツールでは異なるモデルを採用しています。" +"An error except when defined by the context interpreting the specification." +msgstr "仕様を通訳する文脈で定義された場合を除くエラー。" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" -msgstr "ファイルフォーマット" +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" +msgstr "``test``" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/dependency-specifiers.rst:277 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 "" -"エントリポイントは、配布物の `*.dist-info` ディレクトリの中の :file:" -"`entry_points.txt` と呼ばれるファイル内で定義されます。これは、インストール済" -"みの配布物に関しては :ref:`インストール済みパッケージを記録する ` 、 wheels に関しては :ref:`バイナリ配布物のフォーマット " -"` に記述されます。このファイルでは UTF-8 エンコー" -"ディングを使います。" +"The ``implementation_version`` marker variable is derived from :py:data:`sys." +"implementation.version `:" +msgstr "" +"``implementation_version`` マーカ変数は、 :py:data:`sys.implementation." +"version ` から派生したものです :" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/dependency-specifiers.rst:294 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::" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -"ファイルの内容は、 Python の :mod:`configparser` モジュールで読み取ることがで" -"きる INI フォーマットです。しかしながら、 configparser はデフォルトでは変数名" -"を大文字小文字の区別をせずに扱う一方で、エントリポイントでは区別をします。大" -"文字小文字の区別をする configparser はこのようにして作成できます::" +"この環境マーカの節は、当初は :pep:`508` を通して定義されましたが、 :pep:" +"`345` における環境マーカの節を置き換えます。" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" +msgstr "完全な文法" + +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" +msgstr "完全な parsley 文法::" + +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "テストプログラム - もし ``grammar`` 文字列内に文法があれば:" + +#: ../source/specifications/dependency-specifiers.rst:478 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "2015年11月: :pep:`508` を通じてこの仕様が承認されました。" + +#: ../source/specifications/dependency-specifiers.rst:479 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"July 2019: 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 "" -"エントリポイントのファイルでは、名前と値を区切るのに常に ``=`` を使わなければ" -"なりません (他方で configparser は ``:`` で区切ることも許容します) 。" +"2019年6月: ``python_version`` の定義は、Python の将来のバージョンが二桁のメ" +"ジャーバージョンやマイナーバージョンを持つ場合 (例えば 3.10) でもそれを収容で" +"きるように、 ``platform.python_version()[:3]`` から ``'.'.join(platform." +"python_version_tuple()[:2])`` へ `変更されました `_ 。 [#future_versions]_" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/dependency-specifiers.rst:489 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." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -"設定ファイルの各セクションはエントリポイントの各グループを表していて、名前は" -"名前であり、値はオブジェクトへの参照と任意の extras の両方をエンコードしま" -"す。 extras が使われる場合には、角括弧の中にコンマ区切りで列挙します。" +"Python のパッケージをインストールする際に推奨されるツールである pip (http://" +"pip.readthedocs.org/en/stable/)" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/dependency-specifiers.rst:492 +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:495 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." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -"値の内部では、読み取る側はコロンの前後・オブジェクト参照と左角括弧の間・extra" -"の名前と角括弧や区切り文字のコロンの間・右角括弧の後にある空白文字 (連続する" -"複数の空白文字を含む) を許容し無視しなければなりません。 extras の文法は公式" -"に :pep:`508` の一部 (の ``extras`` 部分) として指定されており、値に関する制" -"限事項は :pep:`685` で指定されています。ファイルを書き出すようなツールでは、" -"オブジェクト参照と左角括弧の間に限って空白文字を挿入することが推奨されていま" -"す。" +"Python の将来のバージョンでは、環境マーカ変数の ``python_version`` の定義が問" +"題をはらむかもしれません。 (https://github.com/python/peps/issues/560)" -#: ../source/specifications/entry-points.rst:128 -msgid "Use for scripts" -msgstr "スクリプト向けの使用法" +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "インストールされた配布物の配布元へ直接アクセスする URL を記録する" -#: ../source/specifications/entry-points.rst:130 +#: ../source/specifications/direct-url.rst:8 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 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 "" -"``console_scripts`` と ``gui_scripts``: エントリポイントのふたつのグループ" -"は、パッケージング全体の中で特別な重要性を持っています。このふたつのグループ" -"では、エントリポイントの名前は、パッケージがインストールされた後にシステムの" -"シェルでコマンドとして使えるものでなければなりません。オブジェクト参照は、こ" -"のコマンドが動作する際に引数なしで呼び出される関数を指し示しています。関数" -"は、プロセスの終了コードとして使われる整数を返しても構わず、 ``None`` を返す" -"と ``0`` を返したのと同じに扱われます。" +"この説明文書では、インストール済みの配布物の `*.dist-info` ディレクトリにあ" +"る :file:`direct_url.json` ファイルによって配布物の配布元へ直接アクセスする " +"URL を記録する方法を指定します。 ``*.dist-info`` ディレクトリの一般的な構造と" +"使用方法は、 :ref:`インストール済みパッケージを記録する ` に記述されています。" -#: ../source/specifications/entry-points.rst:138 +#: ../source/specifications/direct-url.rst:17 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"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 "" -"例えば、 ``micmd = memo:main`` というエントリポイントは、 ``micmd`` というコ" -"マンドを生成し、このようにスクリプトを起動することになるでしょう::" +":file:`direct_url.json` ファイルは、要求事項が指定するダイレクト (VCS の URL " +"を含む) 参照 URL からインストールしている時に、インストーラによって :file:`*." +"dist-info` ディレクトリに生成されなければなりません。" -#: ../source/specifications/entry-points.rst:145 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:216 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 :py:data:`sys.stdin`, :py:data:" -"`sys.stdout` and :py:data:`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 file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -"``console_scripts`` と ``gui_scripts`` の違いは、 Windows システムにだけ影響" -"を与えます。 ``console_scripts`` はコンソールで実行できるようにラップされるの" -"で、コンソールに接続されて 入出力に :py:data:`sys.stdin` ・ :py:data:`sys." -"stdout` ・ :py:data:`sys.stderr` を使えます。 ``gui_scripts`` は GUI で実行可" -"能となるようにラップされるので、コンソールなしで起動することができ、しかし、" -"アプリケーション側でリダイレクトしておかない限りは標準入出力を使うことができ" -"ません。他のプラットフォームではこのような区別をしません。" +"他のタイプの要求事項 (すなわち、名前とバージョン指定子) から配布物をインス" +"トールする際には、このファイルを生成してはなりません。" -#: ../source/specifications/entry-points.rst:153 +#: ../source/specifications/direct-url.rst:24 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 JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -"インストールツールは、 ``console_scripts`` と ``gui_scripts`` の両方につい" -"て、インストールスキームのスクリプト用ディレクトリにラッパをセットアップする" -"ものと期待されています。(しかし、インストールツールは) このディレクトリをコマ" -"ンドラインツールを探索するために定義される ``PATH`` 環境変数に入れることにつ" -"いては責任を持ちません。" +"この JSON ファイルは、 :rfc:`8259` に準拠するように UTF-8 で符号化されていな" +"ければならず、シリアル化の方法は :doc:`direct-url-data-structure` でなければ" +"なりません。" -#: ../source/specifications/entry-points.rst:158 +#: ../source/specifications/direct-url.rst:29 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 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 "" -"名前からファイルが作られることと、いくつかのファイルシステムでは大文字小文字" -"を区別しないことから、パッケージはこれらのグループについては大文字か小文字か" -"の違いしかないような名前を使うことを避けるべきです。名前が大文字小文字しか違" -"わない場合のインストールツールの挙動は未定義です。" +"要求された URL が file:// スキームであって VCS からチェックアウトしたものを含" +"むローカルディレクトリを指し示している場合には、インストーラはいかなる VCS 情" +"報をも推定してはならず、従って、いかなる (``vcs_info`` のような) VCS 関連情報" +"をも :file:`direct_url.json` に出力してはなりません。" -#: ../source/specifications/entry-points.rst:166 +#: ../source/specifications/direct-url.rst:36 msgid "" -"October 2017: This specification was written to formalize the existing entry " -"points feature of setuptools (discussion_)." +"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 "" -"2017年10月: setuptools の既存のエントリポイント機能を公式のものとするためのこ" -"の仕様が書かれました (discussion_) 。" +"一般的な規則として、 :file:`direct_url.json` を生成する際には、インストーラは" +"可能な限り要求された URL に含まれる情報を保存するべきです。例えば、 user:" +"password を環境変数から読み込むなら環境変数を参照するような URL として保存さ" +"れるべきであり、 ``requested_revision`` は要求された URL の中に出現するものを" +"極力そのまま反映するべきです。しかしながら、この情報は (``commit_id`` のよう" +"な) もっと精密なデータを使って *精製* されます。" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" -msgstr "外部から管理される環境" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "pip コマンドの例と direct_url.json に与える影響" -#: ../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/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "``direct_url.json`` を生成するコマンド:" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -"Python の導入方法の中には Python をインストールするユーザが全てを管理するもの" -"もある一方で、(Linux ディストリビューションのオペレーティングシステムが提供す" -"るパッケージマネージャや、専用のインストーラを伴うアプリケーションにおけるバ" -"ンドルされた Python 環境のような) 別の手段で準備され管理されるものもありま" -"す。" -#: ../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/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -"そのような環境下で従来の Python のパッケージングツール類を使おうと試みること" -"は、最もうまくいったときでも混乱を招く結果になり、最悪の場合には根底にあるオ" -"ペレーティングシステム全体を完全に破壊してしまうことにもなりかねません。この" -"ような問題を解決する上では、説明文書と互換性ガイドだけが頼りになります。" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/direct-url.rst:51 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`." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" +msgstr "" +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" + +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -"この仕様では ``EXTERNALLY-MANAGED`` というマーカファイルを定義しており、これ" -"によって Python をインストールする際に ``pip`` のような Python に特有のツール" -"群に対してインタプリタのデフォルトのインストール環境にパッケージをインストー" -"ルしたり取り除いたりしないように指示し、その代わりに、エンドユーザに対して :" -"ref:`仮想環境 " +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "2020年3月: :pep:`610` を通じてこの仕様が承認されました。" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "ダイレクト URL データ構造 " + +#: ../source/specifications/direct-url-data-structure.rst:9 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 "\"配布物 \" の短縮系で、" +"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 プロジェクトや VCS 上のソースツリーやローカルのソー" +"スツリーやソースコード配布物や wheel ファイルのような配布物アーティファクトに" +"対してURLを表現することを可能とする、 JSON のシリアル化抽象データ構造の仕様を" +"定義します。" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/direct-url-data-structure.rst:13 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." +"At time of writing, it is not formally specified how to merge the parts of " +"this data structure into a single URL that can be passed to tools. A common " +"representation is the pip URL format (`VCS Support `_), " +"other examples are provided in the :ref:`Version specifier specification " +"`." msgstr "" -"配布物 は、Debian 、 Fedora や FreeBSD のようなそれ自身のオペレー" -"ティングシステム (OS) であっても構いません。あるいは、 Homebrew や MacPorts " -"のような既存の OS の上に重ねて配布物をインストールするものであっても構いませ" -"ん。" +"本稿執筆時点では、ツール群に渡せるようにこのデータ構造の各部分を単一の URL に" +"まとめる方法については公式には指定されていません。よく見られる表現形式は pip " +"URL フォーマット (`VCS サポート `_) で、他の例が :ref:`バー" +"ジョン指定子仕様 ` の中で提供されています。" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/direct-url-data-structure.rst:21 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 Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -"Python のパッケージングの文脈では、\"ディストリビューション \" " -"という用語は別の意味、つまり、 Python 言語で書かれたソフトウェアのひとつの部" -"品のソースコード配布パッケージまたはバイナリ配布パッケージ、即ち " -"``setuptools.dist.Distribution`` 乃至 \"sdist\" の意味での配布物という意味を" -"持つので、この文書では短縮された用語である \"ディストロ \" を使いま" -"す。混乱を避けるために、この文書では \"ディストリビューション " -"\" をそのままでは使わないことにします。 Python パッケージングの" -"意味で使う時は完全形の \"配布パッケージ \" または単に " -"\"パッケージ \" を使います (後述します)。" +"直接 URL データ構造は辞書でなければならず、 :rfc:`8259` に従って JSON にシリ" +"アライズできなければなりません。" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Its content must be a valid URL according to the `WHATWG URL " +"Standard `_." msgstr "" -"ディストロを提供する者 - ソフトウェアを収集して公開し、何であれ必要とされる修" -"正を加えるチームまたは企業 - は、その **配布者 ** です。" +"少なくとも二つのフィールドが含まれていなければなりません。一つ目は " +"``string`` 型の ``url`` です。その内容は、 `WHATWG URL 標準 `_ に従う正当な URL でなければなりません。" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" -msgstr "パッケージ" +#: ../source/specifications/direct-url-data-structure.rst:28 +msgid "" +"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 archive 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 "" +"``url`` が何を参照しているかによって、二つ目のフィールドは ``vcs_info`` " +"(``url`` が VCS 参照である場合)・ ``archive_info`` (``url`` がソースコード" +"アーカイブか wheel である場合)・ ``dir_info`` (``url`` がローカルディレクトリ" +"である場合) のうちのいずれか一つでなければなりません。これらの info フィール" +"ドは、(空である場合もありますが) 以下に定義するキー群を持つことができるサブ" +"ディレクトリを値として持ちます。" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/direct-url-data-structure.rst:34 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." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -"インストールすることができ、Python 内で使うことができるソフトウエアの単位。つ" -"まり、これは Python 特有のパッケージングツールが :term:`配布パッケージ " -"` または単に \"配布物\" と呼びがちなものを参照していま" -"す; 口語的な省略形である \"配布物\" は Python Package Index の意味で使われま" -"す。" +"固持する場合には、``url`` は、セキュリティ上の理由から、機微に関わる認証情報" +"をすべて削除しておかなければなりません。" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/direct-url-data-structure.rst:37 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 user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -"この説明文書は \"配布物 \" を Python モジュールを含んでいてインポー" -"ト可能なものの名前という意味では使いませんが、多くの場合、 配布パッケージは同" -"名のインポート可能な単一のパッケージから構成されています。" +"URLの user:password の部分は、しかしながら、次に述べる正規表現に合致する形" +"で、環境変数から構成しても構いません:" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/direct-url-data-structure.rst:45 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.)" +"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 "" -"この説明文書では、\"パッケージ \" という言葉で (``.deb`` や ``." -"rpm`` ファイルのような) ディストロのパッケージマネージャがインストールする単" -"位を参照することはしません。必要な場合には \"ディストロのパッケージ\" などと" -"言い換えて使います。 (再掲になりますが、多くの場合には、 Python パッケージが" -"ディストロのパッケージとして出荷される場合には Python パッケージの名称に " -"``python-`` を付け加えます。)" +"さらに、 URL の user:password 部分は、広く知られたセキュリティ的に問題のない" +"文字列であっても構いません。典型的な例としては、 ``ssh://git@gitlab.com/user/" +"repo`` のような URL における ``git`` を挙げることができます。" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" -msgstr "Python 特有のパッケージマネージャ" +#: ../source/specifications/direct-url-data-structure.rst:50 +msgid "VCS URLs" +msgstr "VCS URL群" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/direct-url-data-structure.rst:52 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 ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -"Python パッケージング標準 を満足する形で Python " -"パッケージをインストール・アップグレード・削除するためのツール。最もよく知ら" -"れた Python 特有のパッケージマネージャは pip_ です; 他の例には、 ``setup." -"py`` コマンドを直接に使う方法と同様、古い `Easy Install コマンド `_ が含まれます。" +"``url`` が VCS リポジトリを参照している場合、 以下のキー群を伴った " +"``vcs_info`` キーが辞書に存在していなければなりません:" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/direct-url-data-structure.rst:55 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"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 "" -"(``easy_install`` コマンドは、2021 年 1 月 23 日にリリースされた setuptools " -"のバージョン 52 で除去されています。)" +"(``git`` ・ ``hg`` ・ ``bzr`` ・ ``svn`` のいずれかのような) VCS の名前を含ん" +"だ ``vcs`` キー (``string`` 型) が存在していなければなりません。その他の VCS " +"については、この仕様を修正するための PEP を書くことによって登録されるべきで" +"す。当該 VCS の checkout/download コマンドへの翻訳をしなくてもインストーラが " +"手を離してしまえるようにするために、 ``url`` の値は対応する VCS と齟齬のない" +"ものでなければなりません。" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/direct-url-data-structure.rst:61 +#, fuzzy +#| 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) " +#| "to install." 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 ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." msgstr "" +"``requested_revision`` キー (``string`` 型) は、どのブランチ・タグ・リファレ" +"ンス・コミット・リビジョンその他をインストールするのかを指定するために存在し" +"ていても構いません。" -#: ../source/specifications/externally-managed-environments.rst:118 -#, fuzzy -msgid "distro package manager" -msgstr "macOS インストーラとパッケージマネージャ" +#: ../source/specifications/direct-url-data-structure.rst:65 +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 "" +"``commit_id`` キー (``string`` 型) は、正確にどのコミットまたはリビジョンがイ" +"ンストールされた/されるかを示すもので、必須のキーです。 VCS がリビジョン識別" +"子に基づくコミットハッシュをサポートしているなら、インストールされたものの" +"ソースコードの不変のバージョンを指し示す目的で、そのようなコミットハッシュを " +"``commit_id`` として使わなければなりません。" + +#: ../source/specifications/direct-url-data-structure.rst:73 +msgid "Archive URLs" +msgstr "アーカイブ URL 群" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/direct-url-data-structure.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." +"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/externally-managed-environments.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:78 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 ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" +"``hashes`` キーは、ハッシュ名から16進数表記のファイルハッシュ値への対応を保持" +"する辞書として存在するべきです。" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/direct-url-data-structure.rst:81 +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/externally-managed-environments.rst:121 +#: ../source/specifications/direct-url-data-structure.rst:85 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "これらのハッシュの名前は、常に小文字に正規化されているべきです。" + +#: ../source/specifications/direct-url-data-structure.rst:87 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." +"Any hash algorithm available via :py:mod:`hashlib` (specifically any that " +"can be passed to :py:func:`hashlib.new()` and do not require additional " +"parameters) can be used as a key for the hashes dictionary. At least one " +"secure algorithm from :py:data:`hashlib.algorithms_guaranteed` SHOULD always " +"be included. At time of writing, ``sha256`` specifically is recommended." msgstr "" +":py:mod:`hash lib` 経由で利用可能なハッシュアルゴリズム (とりわけ、 :py:func:" +"`hashlib.new()` に渡すことができて、かつ、それ以上のパラメータを必要としない" +"もの) はどれでも、ハッシュ値を格納する辞書のキーとして用いることができま" +"す。 :py:data:`hashlib.algorithms_garanteed` から安全なアルゴリズムを少なくと" +"もひとつ選択して含めるべきです。執筆時点では、 ``sha256`` が特に推奨されてい" +"ます。" -#: ../source/specifications/externally-managed-environments.rst:132 -#, fuzzy -msgid "This specification is twofold." -msgstr "PyPA 仕様" - -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/direct-url-data-structure.rst:93 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." +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" +"非推奨となった ``hash`` キー (``string`` 型) は、後方互換性を保つ目的でなら " +"``=`` を値に取る形で存在していても構いません。" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:96 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." +"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/externally-managed-environments.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:100 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." +"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/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "Local directories" +msgstr "ローカルディレクトリ" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" +"``url`` がローカルのディレクトリを参照している場合には、以下のキーを含む辞書" +"として ``dir_info`` キーが存在していなければなりません。" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/direct-url-data-structure.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:" +"``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/externally-managed-environments.rst:167 +#: ../source/specifications/direct-url-data-structure.rst:113 msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +"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/externally-managed-environments.rst:170 +#: ../source/specifications/direct-url-data-structure.rst:119 +msgid "Projects in subdirectories" +msgstr "サブディレクトリ内のプロジェクト群" + +#: ../source/specifications/direct-url-data-structure.rst:121 msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +"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/externally-managed-environments.rst:173 +#: ../source/specifications/direct-url-data-structure.rst:126 +msgid "Registered VCS" +msgstr "登録済みの VCS" + +#: ../source/specifications/direct-url-data-structure.rst:128 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." +"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/externally-managed-environments.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:138 +msgid "Git" +msgstr "Git" + +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 +msgid "Home page" +msgstr "ホームページ" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 +msgid "vcs command" +msgstr "vcs コマンド" + +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 +msgid "git" +msgstr "git" + +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 +msgid "``vcs`` field" +msgstr "``vcs`` フィールド" + +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``requested_revision`` field" +msgstr "``requested_revision`` フィールド" + +#: ../source/specifications/direct-url-data-structure.rst:150 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." +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" +"タグ名・ブランチ名・Git 参照・コミットハッシュ・短縮型コミットハッシュ・その" +"他のコミットハッシュ的なもの。" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "``commit_id`` field" +msgstr "``commit_id`` フィールド" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "コミットハッシュ (16進数で40文字のSHA1)。" + +#: ../source/specifications/direct-url-data-structure.rst:158 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``." +"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/direct-url-data-structure.rst:165 +msgid "Mercurial" +msgstr "Mercurial" + +#: ../source/specifications/direct-url-data-structure.rst:168 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 +msgid "hg" +msgstr "hg" + +#: ../source/specifications/direct-url-data-structure.rst:177 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "タグ名・ブランチ名・チェンジセット ID ・短縮型チェンジセット ID。" + +#: ../source/specifications/direct-url-data-structure.rst:180 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "チェンジセット ID (16 進数で 40 文字)。" + +#: ../source/specifications/direct-url-data-structure.rst:183 +msgid "Bazaar" +msgstr "Bazaar" + +#: ../source/specifications/direct-url-data-structure.rst:186 +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.breezy-vcs.org/" + +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 +msgid "bzr" +msgstr "bzr" + +#: ../source/specifications/direct-url-data-structure.rst:195 +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." +#: ../source/specifications/direct-url-data-structure.rst:198 +msgid "A revision id." +msgstr "リビジョン id 。" + +#: ../source/specifications/direct-url-data-structure.rst:201 +msgid "Subversion" 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/direct-url-data-structure.rst:204 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 +msgid "svn" +msgstr "svn" + +#: ../source/specifications/direct-url-data-structure.rst:213 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:" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" +"``requested_revision`` は、 ``svn checkout`` ``--revision`` オプションと互換" +"でなければなりません。 Subversion では、ブランチまたはタグは ``url`` の一部で" +"す。" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/direct-url-data-structure.rst:217 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." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" +"Subversion は大域的にユニークな識別子をサポートしていないので、このフィールド" +"は当該リポジトリにおける Subversion のリビジョン番号です。" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:222 +msgid "JSON Schema" +msgstr "JSON スキーマ" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/direct-url-data-structure.rst:224 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." +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" msgstr "" +"以下に述べる JSON スキーマを ``direct_url.json`` の内容を検証するために使うこ" +"とができます:" -#: ../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:346 +msgid "Source archive:" +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." -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:359 +msgid "Git URL with tag and commit-hash:" +msgstr "タグおよびコミットハッシュ付きの Git のURL:" -#: ../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:372 +msgid "Local directory:" +msgstr "ローカルディレクトリ:" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:381 +msgid "Local directory in editable mode:" +msgstr "編集可能モード状態にあるローカルディレクトリ:" -#: ../source/specifications/externally-managed-environments.rst:273 +#: ../source/specifications/direct-url-data-structure.rst:396 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/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +"March 2020: This specification was approved through :pep:`610`, defining the " +"``direct_url.json`` metadata file." msgstr "" +"2020年3月: ``direct_url.json`` メタデータファイルを定義するこの仕様は、 :pep:" +"`610` を通じて承認されました。" -#: ../source/specifications/externally-managed-environments.rst:279 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." msgstr "" +"2023年1月: ``archive_info.hashes`` キーを追加しました (`議論 `_) 。" -#: ../source/specifications/externally-managed-environments.rst:283 -#, fuzzy -msgid "Guide users towards virtual environments" -msgstr "仮想環境のランタイムを識別する" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "エントリポイントの仕様" -#: ../source/specifications/externally-managed-environments.rst:285 +#: ../source/specifications/entry-points.rst:7 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." +"*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/externally-managed-environments.rst:293 +#: ../source/specifications/entry-points.rst:11 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." +"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 "" +"配布物では、それぞれが関数を参照するような ``console_scripts`` エントリポイン" +"トを指定することができます。 *pip* (または console_scripts を認識する他のイン" +"ストーラ) が配布物をインストールする際に、各エントリポイントのコマンドライン" +"ラッパを生成します。" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../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 "" +"アプリケーションは、プラグインをロードするためにエントリポイントを用いること" +"ができます; 例えば、 Pygments (シンタックスハイライトを行うツール) は追加的な" +"字句解析器を使うことが可能であり、また、別にインストールされたパッケージから" +"提供されるスタイルを使うことができます。この件の詳細については、 :doc:`/" +"guides/creating-and-discovering-plugins` を見てください。" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/entry-points.rst:19 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 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 :py:mod:`importlib.metadata`. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"``setuptools`` to publish :py:mod:`importlib.metadata` compatible entry " +"point metadata, and runtime libraries other than :py:mod:`importlib." +"metadata` to portably read published entry point metadata (potentially with " +"different caching and conflict resolution strategies)." msgstr "" +"エントリポイントのファイルフォーマットは、元々は、 setuptools でビルドされた" +"パッケージが、動作時 (ランタイム) に :py:mod:`importlib.metadata` で読み取ら" +"れるであろうと思われるインテグレーションポイントメタデータを提供できるように" +"と開発されました。現在では、 ``setuptools`` 以外のビルドツールが :py:mod:" +"`importlib.metadata` と互換性のあるエントリポイントのメタデータを公開し、 :" +"py:mod:`importlib.metadata` 以外のランタイムライブラリが移植可能な形で公開さ" +"れているエントリポイントのメタデータを (潜在的には、たとえ異なるキャッシング" +"と衝突回避の戦略を採用していたとしても) 読み取ることができるようにと PyPA 相" +"互互換性仕様において定義されています。" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" -msgstr "" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +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/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" +"概念的に、エントリポイントは３個の属性を持たなければならないと定義されていま" +"す:" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/entry-points.rst:32 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 **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 "" +"エントリポイントが属する *group* は、それがどのような種類のオブジェクトを提供" +"するのかを示します。例えば、 ``console_scripts`` グループはコマンドとして使え" +"る関数を参照するエントリポイント用であり、一方、 ``pygments.styles`` は " +"pygments スタイルを定義するクラスを提供するグループです。利用する側 (コン" +"シューマ) は、通常、期待するインタフェースを定義しています。衝突を避けるため" +"に、新しいグループを定義するのであればコンシューマは自身の PyPI での名前の後" +"に ``.`` を後置したもので始まるグループ名を使うべきです。グループ名は、ひとつ" +"かそれ以上の文字・数字・アンダースコアをドット文字で区切ったもの (正規表現で " +"``^\\w+(\\.\\w)*$``) でなければなりません。" -#: ../source/specifications/externally-managed-environments.rst:341 +#: ../source/specifications/entry-points.rst:42 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 **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 "" +"グループ内では、エントリポイントを **name** で識別します。このことの正確な意" +"味は利用する側次第です。コンソールスクリプトでは、エントリポイントの名前はそ" +"のコマンドを起動するのに使われる名前です。配布物の内部では、エントリポイント" +"の名前は一意に決まるべきです。別の配布物が同じ名前を提供する場合には、利用す" +"る側でそのような衝突をどのように扱うのかを決めます。名前は ``=`` を除いてどん" +"な文字を含んでいても構いませんが、空白文字で始まったり終わったりすることはで" +"きず、 ``[`` で始まることもできません。エントリポイントをこれから作るのであれ" +"ば、文字・数字・アンダースコア・ドットとダッシュ (正規表現で言うと " +"``[\\w.-]+``) だけを用いることが推奨されています。" -#: ../source/specifications/externally-managed-environments.rst:349 +#: ../source/specifications/entry-points.rst:51 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``." +"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/externally-managed-environments.rst:355 +#: ../source/specifications/entry-points.rst:64 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." +"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/externally-managed-environments.rst:367 +#: ../source/specifications/entry-points.rst:68 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." +"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 "" +"さらに追加のプロパティがあります: **extras** は、エントリポイントを提供する配" +"布物の追加的な機能をを識別する１組みの文字列です。もし指定されていれば、その" +"ような 'extras' の依存関係をエントリポイントが要求しています。メタデータの" +"フィールド :ref:`metadata_provides_extra` を見てください。" -#: ../source/specifications/externally-managed-environments.rst:377 +#: ../source/specifications/entry-points.rst:73 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." +"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/externally-managed-environments.rst:383 +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "ファイルフォーマット" + +#: ../source/specifications/entry-points.rst:82 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." +"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 "" +"エントリポイントは、配布物の `*.dist-info` ディレクトリの中の :file:" +"`entry_points.txt` と呼ばれるファイル内で定義されます。これは、インストール済" +"みの配布物に関しては :ref:`インストール済みパッケージを記録する ` 、 wheels に関しては :ref:`バイナリ配布物のフォーマット " +"` に記述されます。このファイルでは UTF-8 エンコー" +"ディングを使います。" -#: ../source/specifications/externally-managed-environments.rst:393 +#: ../source/specifications/entry-points.rst:88 msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +"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/externally-managed-environments.rst:396 +#: ../source/specifications/entry-points.rst:98 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 entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" +"エントリポイントのファイルでは、名前と値を区切るのに常に ``=`` を使わなければ" +"なりません (他方で configparser は ``:`` で区切ることも許容します) 。" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -msgid "Implementation Notes" -msgstr "文書の類型" - -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/entry-points.rst:101 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"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/externally-managed-environments.rst:415 +#: ../source/specifications/entry-points.rst:105 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:" +"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 "" +"値の内部では、読み取る側はコロンの前後・オブジェクト参照と左角括弧の間・extra" +"の名前と角括弧や区切り文字のコロンの間・右角括弧の後にある空白文字 (連続する" +"複数の空白文字を含む) を許容し無視しなければなりません。 extras の文法は公式" +"に :pep:`508` の一部 (の ``extras`` 部分) として指定されており、値に関する制" +"限事項は :pep:`685` で指定されています。ファイルを書き出すようなツールでは、" +"オブジェクト参照と左角括弧の間に限って空白文字を挿入することが推奨されていま" +"す。" -#: ../source/specifications/externally-managed-environments.rst:422 -#, fuzzy -msgid "``pip install``" -msgstr "はい (``python -m pip uninstall``)" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "スクリプト向けの使用法" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/entry-points.rst:130 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"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 "" +"``console_scripts`` と ``gui_scripts``: エントリポイントのふたつのグループ" +"は、パッケージング全体の中で特別な重要性を持っています。このふたつのグループ" +"では、エントリポイントの名前は、パッケージがインストールされた後にシステムの" +"シェルでコマンドとして使えるものでなければなりません。オブジェクト参照は、こ" +"のコマンドが動作する際に引数なしで呼び出される関数を指し示しています。関数" +"は、プロセスの終了コードとして使われる整数を返しても構わず、 ``None`` を返す" +"と ``0`` を返したのと同じに扱われます。" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../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 "" +"例えば、 ``micmd = memo:main`` というエントリポイントは、 ``micmd`` というコ" +"マンドを生成し、このようにスクリプトを起動することになるでしょう::" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../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 :py:data:`sys.stdin`, :py:data:" +"`sys.stdout` and :py:data:`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 "" +"``console_scripts`` と ``gui_scripts`` の違いは、 Windows システムにだけ影響" +"を与えます。 ``console_scripts`` はコンソールで実行できるようにラップされるの" +"で、コンソールに接続されて 入出力に :py:data:`sys.stdin` ・ :py:data:`sys." +"stdout` ・ :py:data:`sys.stderr` を使えます。 ``gui_scripts`` は GUI で実行可" +"能となるようにラップされるので、コンソールなしで起動することができ、しかし、" +"アプリケーション側でリダイレクトしておかない限りは標準入出力を使うことができ" +"ません。他のプラットフォームではこのような区別をしません。" -#: ../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')``." +#: ../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 "" +"インストールツールは、 ``console_scripts`` と ``gui_scripts`` の両方につい" +"て、インストールスキームのスクリプト用ディレクトリにラッパをセットアップする" +"ものと期待されています。(しかし、インストールツールは) このディレクトリをコマ" +"ンドラインツールを探索するために定義される ``PATH`` 環境変数に入れることにつ" +"いては責任を持ちません。" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/entry-points.rst:158 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"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:433 +#: ../source/specifications/entry-points.rst:166 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\")``." +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." msgstr "" +"2017年10月: setuptools の既存のエントリポイント機能を公式のものとするためのこ" +"の仕様が書かれました (discussion_) 。" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "外部から管理される環境" + +#: ../source/specifications/externally-managed-environments.rst:8 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." +"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 "" +"Python の導入方法の中には Python をインストールするユーザが全てを管理するもの" +"もある一方で、(Linux ディストリビューションのオペレーティングシステムが提供す" +"るパッケージマネージャや、専用のインストーラを伴うアプリケーションにおけるバ" +"ンドルされた Python 環境のような) 別の手段で準備され管理されるものもありま" +"す。" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/externally-managed-environments.rst:13 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." +"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 "" +"そのような環境下で従来の Python のパッケージングツール類を使おうと試みること" +"は、最もうまくいったときでも混乱を招く結果になり、最悪の場合には根底にあるオ" +"ペレーティングシステム全体を完全に破壊してしまうことにもなりかねません。この" +"ような問題を解決する上では、説明文書と互換性ガイドだけが頼りになります。" -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "著作権" - -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"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 "" +"この仕様では ``EXTERNALLY-MANAGED`` というマーカファイルを定義しており、これ" +"によって Python をインストールする際に ``pip`` のような Python に特有のツール" +"群に対してインタプリタのデフォルトのインストール環境にパッケージをインストー" +"ルしたり取り除いたりしないように指示し、その代わりに、エンドユーザに対して :" +"ref:`仮想環境 `__." +"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 "" -"これは、 Python パッケージングオーソリティが維持管理している現時点で有効な相" -"互互換性の使用です。これらの標準を更新し新たな標準を提案するプロセスは、 " -"`pypa.io `__ に文書化されてい" -"ます。" +"この仕様書で用いられる用語のいくつかには、それが置かれた文脈に従って複数の意" +"味を持つものがあります。明確性のために、この仕様書では以下の用語を特定の意味" +"で使用します:" -#: ../source/specifications/inline-script-metadata.rst:3 -#, fuzzy -msgid "Inline script metadata" -msgstr "プロジェクトのメタデータを宣言する" +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "配布物 " -#: ../source/specifications/inline-script-metadata.rst:5 +#: ../source/specifications/externally-managed-environments.rst:39 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." +"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/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 "" +"配布物 は、Debian 、 Fedora や FreeBSD のようなそれ自身のオペレー" +"ティングシステム (OS) であっても構いません。あるいは、 Homebrew や MacPorts " +"のような既存の OS の上に重ねて配布物をインストールするものであっても構いませ" +"ん。" -#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"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 "" +"Python のパッケージングの文脈では、\"ディストリビューション \" " +"という用語は別の意味、つまり、 Python 言語で書かれたソフトウェアのひとつの部" +"品のソースコード配布パッケージまたはバイナリ配布パッケージ、即ち " +"``setuptools.dist.Distribution`` 乃至 \"sdist\" の意味での配布物という意味を" +"持つので、この文書では短縮された用語である \"ディストロ \" を使いま" +"す。混乱を避けるために、この文書では \"ディストリビューション " +"\" をそのままでは使わないことにします。 Python パッケージングの" +"意味で使う時は完全形の \"配布パッケージ \" または単に " +"\"パッケージ \" を使います (後述します)。" -#: ../source/specifications/inline-script-metadata.rst:18 +#: ../source/specifications/externally-managed-environments.rst:60 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 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/inline-script-metadata.rst:26 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "パッケージ" + +#: ../source/specifications/externally-managed-environments.rst:64 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 ``#``)." +"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 "" +"インストールすることができ、Python 内で使うことができるソフトウエアの単位。つ" +"まり、これは Python 特有のパッケージングツールが :term:`配布パッケージ " +"` または単に \"配布物\" と呼びがちなものを参照していま" +"す; 口語的な省略形である \"配布物\" は Python Package Index の意味で使われま" +"す。" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/externally-managed-environments.rst:70 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:" +"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 "" +"この説明文書は \"配布物 \" を Python モジュールを含んでいてインポー" +"ト可能なものの名前という意味では使いませんが、多くの場合、 配布パッケージは同" +"名のインポート可能な単一のパッケージから構成されています。" -#: ../source/specifications/inline-script-metadata.rst:49 +#: ../source/specifications/externally-managed-environments.rst:75 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." +"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 "" +"この説明文書では、\"パッケージ \" という言葉で (``.deb`` や ``." +"rpm`` ファイルのような) ディストロのパッケージマネージャがインストールする単" +"位を参照することはしません。必要な場合には \"ディストロのパッケージ\" などと" +"言い換えて使います。 (再掲になりますが、多くの場合には、 Python パッケージが" +"ディストロのパッケージとして出荷される場合には Python パッケージの名称に " +"``python-`` を付け加えます。)" -#: ../source/specifications/inline-script-metadata.rst:52 +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "Python 特有のパッケージマネージャ" + +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"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 "" +"Python パッケージング標準 を満足する形で Python " +"パッケージをインストール・アップグレード・削除するためのツール。最もよく知ら" +"れた Python 特有のパッケージマネージャは pip_ です; 他の例には、 ``setup." +"py`` コマンドを直接に使う方法と同様、古い `Easy Install コマンド `_ が含まれます。" -#: ../source/specifications/inline-script-metadata.rst:55 +#: ../source/specifications/externally-managed-environments.rst:92 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." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" +"(``easy_install`` コマンドは、2021 年 1 月 23 日にリリースされた setuptools " +"のバージョン 52 で除去されています。)" -#: ../source/specifications/inline-script-metadata.rst:58 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"(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/inline-script-metadata.rst:65 +#: ../source/specifications/externally-managed-environments.rst:118 +#, fuzzy +msgid "distro package manager" +msgstr "macOS インストーラとパッケージマネージャ" + +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"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/inline-script-metadata.rst:68 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this specification." +"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/inline-script-metadata.rst:72 -msgid "script type" +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:74 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"The first type of metadata block is named ``script``, which contains script " -"metadata (dependency data and tool configuration)." +"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/inline-script-metadata.rst:77 +#: ../source/specifications/externally-managed-environments.rst:132 +#, fuzzy +msgid "This specification is twofold." +msgstr "PyPA 仕様" + +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"This document MAY include the top-level fields ``dependencies`` and " -"``requires-python``, and MAY optionally include a ``[tool]`` table." +"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/inline-script-metadata.rst:80 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"The ``[tool]`` MAY be used by any tool, script runner or otherwise, to " -"configure behavior. It has the same semantics as the :ref:`[tool] table in " -"pyproject.toml `." +"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/inline-script-metadata.rst:84 -msgid "The top-level fields are:" +#: ../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:86 -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/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 +#: ../source/specifications/externally-managed-environments.rst:162 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 `." +"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/inline-script-metadata.rst:93 +#: ../source/specifications/externally-managed-environments.rst:167 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." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "Example" -msgstr "例" - -#: ../source/specifications/inline-script-metadata.rst:100 -msgid "The following is an example of a script with embedded metadata:" +#: ../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:121 -#, fuzzy -msgid "Reference Implementation" -msgstr "文書の類型" - -#: ../source/specifications/inline-script-metadata.rst:123 +#: ../source/specifications/externally-managed-environments.rst:173 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"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/inline-script-metadata.rst:149 +#: ../source/specifications/externally-managed-environments.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__." +"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/inline-script-metadata.rst:180 +#: ../source/specifications/externally-managed-environments.rst:182 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 ``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/inline-script-metadata.rst:184 +#: ../source/specifications/externally-managed-environments.rst:200 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"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/inline-script-metadata.rst:203 -#: ../source/specifications/simple-repository-api.rst:815 -#, fuzzy -msgid "Recommendations" -msgstr "オススメのツール" - -#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/externally-managed-environments.rst:206 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." +"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:213 +#: ../source/specifications/externally-managed-environments.rst:230 msgid "" -"October 2023: This specification was conditionally approved through :pep:" -"`723`." +"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/inline-script-metadata.rst:214 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"January 2024: Through amendments to :pep:`723`, the ``pyproject`` metadata " -"block type was renamed to ``script``, and the ``[run]`` table was dropped, " -"making the ``dependencies`` and ``requires-python`` keys top-level. " -"Additionally, the specification is no longer provisional." +"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/name-normalization.rst:3 -#, fuzzy -msgid "Names and normalization" -msgstr "パッケージ名の正規化" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" -#: ../source/specifications/name-normalization.rst:5 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"This specification defines the format that names for packages and extras are " -"required to follow. It also describes how to normalize them, which should be " -"done before lookups and comparisons." +"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/name-normalization.rst:13 -#, fuzzy -msgid "Name format" -msgstr "ファイルフォーマット" - -#: ../source/specifications/name-normalization.rst:15 -#, fuzzy +#: ../source/specifications/externally-managed-environments.rst:255 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 :py:data:`re.IGNORECASE`)::" +"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 "" -"正当な名前は ASCII 文字・数字・ピリオド・アンダースコア・ハイフンだけで構成さ" -"れているものです。名前の先頭と末尾は文字か数字でなければなりません。正当なプ" -"ロジェクト名は、次の正規表現に (``re.IGNORECASE`` 付きで) マッチするものに限" -"らるということになります::" - -#: ../source/specifications/name-normalization.rst:26 -#, fuzzy -msgid "Name normalization" -msgstr "正規化" -#: ../source/specifications/name-normalization.rst:28 +#: ../source/specifications/externally-managed-environments.rst:262 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:" +"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 "" -"名前は、すべての文字を小文字にして、 ``.`` ・ ``,`` ・ ``_`` の文字が連続で１" -"個以上出現したらそれを単独の ``-`` の文字に置き換えるべきです。これは、 " -"Python の re モジュールを使って実装することができます:" - -#: ../source/specifications/name-normalization.rst:39 -msgid "This means that the following names are all equivalent:" -msgstr "次に挙げる名前はすべて同等ということになります:" - -#: ../source/specifications/name-normalization.rst:41 -#, fuzzy -msgid "``friendly-bard`` (normalized form)" -msgstr "``friendly-bard`` (正規化形式)" - -#: ../source/specifications/name-normalization.rst:42 -msgid "``Friendly-Bard``" -msgstr "``Friendly-Bard``" - -#: ../source/specifications/name-normalization.rst:43 -msgid "``FRIENDLY-BARD``" -msgstr "``FRIENDLY-BARD``" - -#: ../source/specifications/name-normalization.rst:44 -msgid "``friendly.bard``" -msgstr "``friendly.bard``" - -#: ../source/specifications/name-normalization.rst:45 -msgid "``friendly_bard``" -msgstr "``friendly_bard``" - -#: ../source/specifications/name-normalization.rst:46 -msgid "``friendly--bard``" -msgstr "``friendly--bard``" -#: ../source/specifications/name-normalization.rst:47 -#, fuzzy +#: ../source/specifications/externally-managed-environments.rst:266 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" -msgstr "``FrIeNdLy-._.-bArD`` (ひどい書き方の名前の例だが、正当である)" +"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/name-normalization.rst:52 -msgid "" -"September 2015: The specification of name normalized was approved through :" -"pep:`503 <503#normalized-names>`." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/name-normalization.rst:54 +#: ../source/specifications/externally-managed-environments.rst:273 msgid "" -"November 2015: The specification of valid names was approved through :pep:" -"`508 <508#names>`." +"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:6 -msgid "Platform compatibility tags" -msgstr "プラットフォームの互換性タグ" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/externally-managed-environments.rst:279 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." +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -"プラットフォーム相互互換性タグは、特定のプラットフォームと互換であるとビルド" -"ツールが配布物に印を付けることができるようにし、インストーラが自身が動作して" -"いるシステムと互換であるのはどの配布物であるかを理解できるようにします。" - -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." -msgstr "タグの書式は、 ``{python tag}-{abi tag}-{platform tag}`` です。" - -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid "python tag" -msgstr "python タグ" - -#: ../source/specifications/platform-compatibility-tags.rst:19 -msgid "'py27', 'cp33'" -msgstr "'py27' ・ 'cp33'" - -#: ../source/specifications/platform-compatibility-tags.rst:21 -msgid "'cp32dmu', 'none'" -msgstr "'cp33dmu' ・ 'none'" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "'linux_x86_64', 'any'" -msgstr "'linux_x86_64' ・ 'any'" +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "仮想環境のランタイムを識別する" -#: ../source/specifications/platform-compatibility-tags.rst:25 +#: ../source/specifications/externally-managed-environments.rst:285 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 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 "" -"例えば、``py27-none-any`` というタグは、abi に対する要求なしに任意のプラット" -"フォームで Python 2.7 (任意の Python 2.7 実装) との互換性を持つことを意味しま" -"す。" -#: ../source/specifications/platform-compatibility-tags.rst:28 +#: ../source/specifications/externally-managed-environments.rst:293 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." +"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 "" -"``wheel`` ビルド済みパッケージのフォーマットは、ファイル名の中にこのようなタ" -"グを ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl`` の形で包含しています。他のパッケージフォーマットにはそれ" -"ぞれ独自の慣習があるかもしれません。" -#: ../source/specifications/platform-compatibility-tags.rst:33 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -"どのようなタグであれ、その中に潜在的に含まれる空白文字は ``_`` で置換されるべ" -"きです。" - -#: ../source/specifications/platform-compatibility-tags.rst:37 -msgid "Python Tag" -msgstr "Python タグ" -#: ../source/specifications/platform-compatibility-tags.rst:39 +#: ../source/specifications/externally-managed-environments.rst:310 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"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 "" -"Python タグは、配布物が必要とする実装やバージョンを示します。主要な実装には短" -"縮系のコードがあって、当初は:" - -#: ../source/specifications/platform-compatibility-tags.rst:42 -msgid "py: Generic Python (does not require implementation-specific features)" -msgstr "py: 一般的な Python (実装に特有な機能を要求しません)" - -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "cp: CPython" -msgstr "cp: CPython" - -#: ../source/specifications/platform-compatibility-tags.rst:44 -msgid "ip: IronPython" -msgstr "ip: IronPython" -#: ../source/specifications/platform-compatibility-tags.rst:45 -msgid "pp: PyPy" -msgstr "pp: PyPy" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:46 -msgid "jy: Jython" -msgstr "jy: Jython" +#: ../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:48 -#, fuzzy +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Other Python implementations should use :py:data:`sys.implementation.name " -"`." -msgstr "ほかの Python 実装には ``sys.implementation.name`` を用いるべきです。" +"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:50 +#: ../source/specifications/externally-managed-environments.rst:341 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``." +"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 "" -"バージョンは ``py_version_nodot`` です。 CPython は no dot にせずに済ませます" -"が、必要な場合には代わりにアンダースコア文字 ``_`` が使用されます。 PyPy は、" -"おそらく、ここに ``pp18`` や ``pp19`` といったそれ自身のバージョンを使いま" -"す。" -#: ../source/specifications/platform-compatibility-tags.rst:54 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"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 "" -"多くの純 Python 配布物では、バージョンは ``2`` や ``3`` や ``py2`` ・ " -"``py3`` といったメジャーバージョンだけにしておくことができます。" -#: ../source/specifications/platform-compatibility-tags.rst:57 +#: ../source/specifications/externally-managed-environments.rst:355 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." +"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 "" -"重要なことは、 ``py2`` や ``py3`` のような major-version-only タグは " -"``py20`` や ``py30`` の短縮形であるわけではないということです。そうではなく" -"て、これらのタグは、パッケージ作成者がいくつものバージョンに互換性を持つ配布" -"物を意図的にリリースしたのです。" -#: ../source/specifications/platform-compatibility-tags.rst:61 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"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 "" -"単一ソースで Python 2/3 に互換性を持つ配布物は、合成タグ ``py2.py3`` を用いる" -"ことができます。 後述の `タグの圧縮された組み合わせ `_ " -"を参照してください。" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "ABI Tag" -msgstr "ABI タグ" +#: ../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:68 +#: ../source/specifications/externally-managed-environments.rst:383 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." +"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 "" -"ABI タグは、いずれかの拡張モジュールによってどのような Python ABI が要求され" -"ているのかを示します。実装依存の ABI 群については、実装 (の名前) は、たとえ" -"ば ``cp33d`` がデバッグオプション付きの CPython 3.3 ABI のことを指すように、 " -"Python タグと同様のやり方で短縮したものを使います。" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../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 "" -"CPython の安定版 ABI のことは、共有ライブラリの拡張子と同様に ``abi3`` と書き" -"ます。" -#: ../source/specifications/platform-compatibility-tags.rst:75 +#: ../source/specifications/externally-managed-environments.rst:396 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." +"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 "" -"非常に不安定な ABI を持つ実装は、そのソースコードのリビジョンやコンパイラフラ" -"グその他の SHA-256 ハッシュ値の最初の６バイトを (BASE64にエンコードされた８文" -"字として) 用いても構いませんが、おそらくはバイナリ配布物を配布することには大" -"きな需要はないでしょう。それぞれの実装のコミュニティで ABI タグをどのように用" -"いるのが最適かを決定すればよいでしょう。" - -#: ../source/specifications/platform-compatibility-tags.rst:83 -msgid "Platform Tag" -msgstr "プラットフォームタグ" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/externally-managed-environments.rst:410 #, fuzzy -msgid "Basic platform tags" -msgstr "プラットフォームタグ" +msgid "Implementation Notes" +msgstr "文書の類型" -#: ../source/specifications/platform-compatibility-tags.rst:88 -#, fuzzy +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"In its simplest form, the platform tag is :py:func:`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 example:" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -"プラットフォームタグは、すべてのハイフン ``-`` とピリオド ``.`` をアンダース" -"コア ``_`` で単純に置き換えた ``sysconfig.get_platform()`` です。 :ref:" -"`distutils` が Python 3.12 で削除されるまでは、これは ``distutils.util." -"get_platform()`` でした。" - -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "win32" -msgstr "win32" -#: ../source/specifications/platform-compatibility-tags.rst:94 -msgid "linux_i386" -msgstr "linux_i386" - -#: ../source/specifications/platform-compatibility-tags.rst:95 -msgid "linux_x86_64" -msgstr "linux_x86_64" - -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "``manylinux``" -msgstr "``manylinux``" - -#: ../source/specifications/platform-compatibility-tags.rst:103 -#, fuzzy +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The simple scheme above is insufficient for public distribution of wheel " -"files to Linux platforms, due to the large ecosystem of Linux platforms and " -"subtle differences between them." +"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 "" -"Linux プラットフォームのエコシステムが巨大であることとそれらの間に微妙な差異" -"があることから、 :pep:`425` で定義されたスキームは、Linux プラットフォーム向" -"けの wheel ファイル (および、一般に \\*nix 向けの wheel ファイル) の公開配布" -"物としては不十分です。" -#: ../source/specifications/platform-compatibility-tags.rst:107 +#: ../source/specifications/externally-managed-environments.rst:422 #, fuzzy +msgid "``pip install``" +msgstr "はい (``python -m pip uninstall``)" + +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"Instead, for those platforms, the ``manylinux`` standard 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." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -"代わりに、 :pep:`600` で Linux プラットフォームの共通のサブセットを表現する" -"``manylinux`` 標準が定義されており、普通の Linux ディストロのほとんどで使え" -"る ``manylinux`` プラットフォームタグ付きの wheel をビルドできるようにしてい" -"ます。" -#: ../source/specifications/platform-compatibility-tags.rst:112 -msgid "" -"The current standard is the future-proof ``manylinux_x_y`` standard. It " -"defines tags of the form ``manylinux_x_y_arch``, where ``x`` and ``y`` are " -"glibc major and minor versions supported (e.g. ``manylinux_2_24_xxx`` should " -"work on any distro using glibc 2.24+), and ``arch`` is the architecture, " -"matching the value of :py:func:`sysconfig.get_platform()` on the system as " -"in the \"simple\" form above." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:118 -msgid "" -"The following older tags are still supported for backward compatibility:" +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:120 +#: ../source/specifications/externally-managed-environments.rst:428 #, fuzzy -msgid "" -"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." -msgstr "" -"``manylinux1`` (:pep:`513`) は、 ``x86_64`` および ``i686`` アーキテクチャを" -"サポートしていて、 2007 年から互換性のある Linux プラットフォームに基づいてい" -"ます。" +msgid "``pip install --user``" +msgstr "はい (``python -m pip uninstall``)" -#: ../source/specifications/platform-compatibility-tags.rst:121 -msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " -"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:125 +#: ../source/specifications/externally-managed-environments.rst:433 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)." +"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 "" -"一般に、古めのバージョンの仕様向けにビルドされた配布物には前方互換性がありま" -"す (というのは、 ``manylinux1`` の配布物はより新しいシステムでも同様に動作す" -"るはずだということです) が、後方互換性はありません (``manylinux2010`` の配布" -"物が 2010 年よりも前に存在していたプラットフォームで動作するとは想定されてい" -"ないということです) 。" -#: ../source/specifications/platform-compatibility-tags.rst:131 +#: ../source/specifications/externally-managed-environments.rst:445 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." +"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 "" -"``manylinux1`` と ``manylinux2010`` は既に end-of-life に達していて、提供され" -"ているビルド環境にはもはやセキュリティアップデートが提供されることはないであ" -"ろうという警告されていることもあって、パッケージ保守者は最も互換性のある仕様" -"をターゲットにするように努力するべきです。" -#: ../source/specifications/platform-compatibility-tags.rst:136 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"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 "" -"適切なプロジェクトがサポートするさまざまな ``manylinux`` 標準の最低限のバー" -"ジョンを次に掲げる表に示します:" - -#: ../source/specifications/platform-compatibility-tags.rst:140 -msgid "Tool" -msgstr "ツール" - -#: ../source/specifications/platform-compatibility-tags.rst:140 -msgid "``manylinux1``" -msgstr "``manylinux1``" - -#: ../source/specifications/platform-compatibility-tags.rst:140 -msgid "``manylinux2010``" -msgstr "``manylinux2010``" - -#: ../source/specifications/platform-compatibility-tags.rst:140 -msgid "``manylinux2014``" -msgstr "``manylinux2014``" - -#: ../source/specifications/platform-compatibility-tags.rst:140 -msgid "``manylinux_x_y``" -msgstr "``manylinux_x_y``" - -#: ../source/specifications/platform-compatibility-tags.rst:142 -msgid "``>=8.1.0``" -msgstr "``>=8.1.0``" - -#: ../source/specifications/platform-compatibility-tags.rst:142 -msgid "``>=19.0``" -msgstr "``>=19.0``" -#: ../source/specifications/platform-compatibility-tags.rst:142 -msgid "``>=19.3``" -msgstr "``>=19.3``" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "著作権" -#: ../source/specifications/platform-compatibility-tags.rst:142 -msgid "``>=20.3``" -msgstr "``>=20.3``" +#: ../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:143 -msgid "auditwheel" -msgstr "auditwheel" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 -msgid "``>=1.0.0``" -msgstr "``>=1.0.0``" +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "PyPA 仕様" -#: ../source/specifications/platform-compatibility-tags.rst:143 -msgid "``>=2.0.0``" -msgstr "``>=2.0.0``" +#: ../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 "" +"これは、 Python パッケージングオーソリティが維持管理している現時点で有効な相" +"互互換性の使用です。これらの標準を更新し新たな標準を提案するプロセスは、 " +"`pypa.io `__ に文書化されてい" +"ます。" -#: ../source/specifications/platform-compatibility-tags.rst:143 -msgid "``>=3.0.0``" -msgstr "``>=3.0.0``" +#: ../source/specifications/inline-script-metadata.rst:3 +#, fuzzy +msgid "Inline script metadata" +msgstr "プロジェクトのメタデータを宣言する" -#: ../source/specifications/platform-compatibility-tags.rst:143 -msgid "``>=3.3.0`` [#]_" -msgstr "``>=3.3.0`` [#]_" +#: ../source/specifications/inline-script-metadata.rst:5 +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/platform-compatibility-tags.rst:146 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/inline-script-metadata.rst:13 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -"audit wheel 3.3.0 では ``manylinux_2_24`` へのサポートだけが追加されました" -#: ../source/specifications/platform-compatibility-tags.rst:150 -#, fuzzy -msgid "``musllinux``" -msgstr "``manylinux``" +#: ../source/specifications/inline-script-metadata.rst:18 +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:152 +#: ../source/specifications/inline-script-metadata.rst:26 msgid "" -"The ``musllinux`` family of tags is similar to ``manylinux``, but for Linux " -"platforms that use the musl_ libc rather than glibc (a prime example being " -"Alpine Linux). The schema is ``musllinux_x_y_arch``, supporting musl ``x.y`` " -"and higher on the architecture ``arch``." +"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/platform-compatibility-tags.rst:157 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"The musl version values can be obtained by executing the musl libc shared " -"library the Python interpreter is currently running on, and parsing the " -"output:" +"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:188 +#: ../source/specifications/inline-script-metadata.rst:49 msgid "" -"There are currently two possible ways to find the musl library’s location " -"that a Python interpreter is running on, either with the system ldd_ " -"command, or by parsing the ``PT_INTERP`` section’s value from the " -"executable’s ELF_ header." +"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/platform-compatibility-tags.rst:194 -msgid "Use" -msgstr "使い方" - -#: ../source/specifications/platform-compatibility-tags.rst:196 +#: ../source/specifications/inline-script-metadata.rst:52 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." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -"タグ類は、 (もしダウンロードが必要なら) 選択可能なビルド済配布物のリストの中" -"からどれをダウンロードするのかをインストーラが決定するために使われます。イン" -"ストーラは、自身がサポートする (pyver, abi, arch) タプルのリストを維持管理し" -"ています。ビルド済配布物のタグがリストに含まれて (``in`` ) いれば、それをイン" -"ストールすることができます。" -#: ../source/specifications/platform-compatibility-tags.rst:202 +#: ../source/specifications/inline-script-metadata.rst:55 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 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 "" -"古い Python リリース向けに発行された純 Python のバージョンにフォールバックす" -"るよりも前に、利用できる中で最も機能を網羅したビルド済配布物 (インストールす" -"る先の環境に最も適したもの) をインストーラがデフォルトで選択することが推奨さ" -"れています。インストーラは、また、受け入れ可能な互換性タグのリストを設定変更" -"したり順序を入れ替えたりする方法を持つことが推奨されています; 例えば、ユーザ" -"は、純 Python であると広報しているビルド済みパッケージだけをダウンロードする" -"ために、 ``*-none-any`` タグだけを受容しても構いません。" -#: ../source/specifications/platform-compatibility-tags.rst:210 +#: ../source/specifications/inline-script-metadata.rst:58 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." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -"互換性はあるがもはや古くなってしまったビルド済みのものを使う選択肢よりもより" -"好ましいという点で、インストーラに望まれるもうひとつの機能は \"可能ならソース" -"コードから再コンパイルする\" でしょう。" -#: ../source/specifications/platform-compatibility-tags.rst:214 +#: ../source/specifications/inline-script-metadata.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):" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -"この事例集は、インストーラを linux_x86_64 システム上の CPython 3.3 のもとで走" -"らせるためのものです。最も好ましいもの (最新版の Python 向けにビルドされたコ" -"ンパイル済みの拡張モジュールが付属している配布物) から、最も好ましくはないも" -"の (古いバージョンの Python でビルドされた純 Python の配布物) へ、という順序" -"で並んでいます:" - -#: ../source/specifications/platform-compatibility-tags.rst:220 -msgid "cp33-cp33m-linux_x86_64" -msgstr "cp33-cp33m-linux_x86_64" - -#: ../source/specifications/platform-compatibility-tags.rst:221 -msgid "cp33-abi3-linux_x86_64" -msgstr "cp33-abi3-linux_x86_64" - -#: ../source/specifications/platform-compatibility-tags.rst:222 -msgid "cp3-abi3-linux_x86_64" -msgstr "cp3-abi3-linux_x86_64" - -#: ../source/specifications/platform-compatibility-tags.rst:223 -msgid "cp33-none-linux_x86_64*" -msgstr "cp33-none-linux_x86_64*" - -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "cp3-none-linux_x86_64*" -msgstr "cp3-none-linux_x86_64*" - -#: ../source/specifications/platform-compatibility-tags.rst:225 -msgid "py33-none-linux_x86_64*" -msgstr "py33-none-linux_x86_64*" - -#: ../source/specifications/platform-compatibility-tags.rst:226 -msgid "py3-none-linux_x86_64*" -msgstr "py3-none-linux_x86_64*" - -#: ../source/specifications/platform-compatibility-tags.rst:227 -msgid "cp33-none-any" -msgstr "cp33-none-any" -#: ../source/specifications/platform-compatibility-tags.rst:228 -msgid "cp3-none-any" -msgstr "cp3-none-any" +#: ../source/specifications/inline-script-metadata.rst:68 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:229 -msgid "py33-none-any" -msgstr "py33-none-any" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "script type" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:230 -msgid "py3-none-any" -msgstr "py3-none-any" +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:231 -msgid "py32-none-any" -msgstr "py32-none-any" +#: ../source/specifications/inline-script-metadata.rst:77 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:232 -msgid "py31-none-any" -msgstr "py31-none-any" +#: ../source/specifications/inline-script-metadata.rst:80 +msgid "" +"The ``[tool]`` MAY be used by any tool, script runner or otherwise, to " +"configure behavior. It has the same semantics as the :ref:`[tool] table in " +"pyproject.toml `." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:233 -msgid "py30-none-any" -msgstr "py30-none-any" +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "The top-level fields are:" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:235 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -"ビルド済み配布物は、サブプロセスとして起動されるネーティブの実行可能ファイル" -"を含んでいるなどのようなC 言語拡張以外の理由によって、特定のプラットフォーム" -"向けであっても構いません。" -#: ../source/specifications/platform-compatibility-tags.rst:239 +#: ../source/specifications/inline-script-metadata.rst:89 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." +"``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 "" -"時々、あるパッケージの特定のバージョンとして複数のビルド済み配布物が存在する" -"ことがあるでしょう。例えば、パッケージ製作者が、 ``cp33-abi3-linux_x86_64`` " -"というタグを付けて追加的な C 言語拡張を含むパッケージをリリースし、そのような" -"ものを含まない同じ配布物に ``py3-none-any`` というタグを付けてリリースするよ" -"うな場合です。(このような場合でも) サポートされるタグのリストで先に出現する方" -"を優先するという理由によって C 言語拡張付きのパッケージがそうでないパッケージ" -"よりも選好されてインストールされるという形で、インデックスによってどちらかに" -"決めることができます。" -#: ../source/specifications/platform-compatibility-tags.rst:248 -msgid "Compressed Tag Sets" -msgstr "圧縮されたタグのセット" - -#: ../source/specifications/platform-compatibility-tags.rst:250 +#: ../source/specifications/inline-script-metadata.rst:93 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::" +"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 "" -"bdists のコンパクトなファイル名で、互換性のあるタグトリプルが複数ある場合にも" -"きちんと動作するものを許容するためには、代わりにファイル名の中のそれぞれのタ" -"グが '.' で分割可能でありソート可能であるような一連のタグになっていることが可" -"能です。例えば、 pip は純 Python のパッケージで、同一のソースコードで Python " -"2 でも 3 でも動作するように書かれていますが、これは ``py2.py3-none-any`` とい" -"うタグを付けた bdist として配布することができるでしょう。単純なタグの完全なリ" -"ストは::" -#: ../source/specifications/platform-compatibility-tags.rst:262 -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." +#: ../source/specifications/inline-script-metadata.rst:98 +msgid "Example" +msgstr "例" + +#: ../source/specifications/inline-script-metadata.rst:100 +msgid "The following is an example of a script with embedded metadata:" msgstr "" -"このスキームを実装する bdist フォーマットは、拡張されたタグ群を bdist に特有" -"のメタデータの中に含んでいるべきです。この圧縮スキームは、サポートされていな" -"いタグや例えば \"cp33-cp31u-win64\" のようにいかなる Python 実装においてもサ" -"ポートされていない \"不可能な\" タグを大量に生成すると思われるので、控えめに" -"使うようにしてください。" -#: ../source/specifications/platform-compatibility-tags.rst:275 -msgid "What tags are used by default?" -msgstr "デフォルトではどんなタグが使われますか？" +#: ../source/specifications/inline-script-metadata.rst:121 +#, fuzzy +msgid "Reference Implementation" +msgstr "文書の類型" -#: ../source/specifications/platform-compatibility-tags.rst:271 +#: ../source/specifications/inline-script-metadata.rst:123 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." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:149 +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 "" -"ツール類は、 ``cp33-cp33m-win32`` のようなアーキテクチャへの依存を示すタグや " -"``py33-none-any`` のような純 Python タグの中で最も好ましいものをデフォルトで" -"採用するべきです。パッケージ製作者がデフォルトをオーバーライドしていたとすれ" -"ば、それは彼らが異なる Python 間での互換性を提供しようという意図があったこと" -"を示しています。" -#: ../source/specifications/platform-compatibility-tags.rst:285 +#: ../source/specifications/inline-script-metadata.rst:180 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"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 "" -"自分の配布物が最新版の Python と相容れない機能を使っているとしたら、どんなタ" -"グを使いますか？" -#: ../source/specifications/platform-compatibility-tags.rst:278 +#: ../source/specifications/inline-script-metadata.rst:184 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." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." 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) などを他の指定子を組み合わせなければなりません。" -#: ../source/specifications/platform-compatibility-tags.rst:290 -msgid "Why isn't there a ``.`` in the Python version number?" -msgstr "Python のバージョン番号に ``.`` がないのはなぜですか?" +#: ../source/specifications/inline-script-metadata.rst:203 +#: ../source/specifications/simple-repository-api.rst:815 +#, fuzzy +msgid "Recommendations" +msgstr "オススメのツール" -#: ../source/specifications/platform-compatibility-tags.rst:288 +#: ../source/specifications/inline-script-metadata.rst:205 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." +"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 "" -"CPython は、数字３個のメジャーリリースなしで 20 年以上にわたって存続してきま" -"した。これはしばらくの間は続くに違いありません。 - や . が周辺のファイル名を" -"区切る役割を果たしているので、他の実装では _ を区切り子として使っても構いませ" -"ん。" -#: ../source/specifications/platform-compatibility-tags.rst:296 +#: ../source/specifications/inline-script-metadata.rst:213 msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +"October 2023: This specification was conditionally approved through :pep:" +"`723`." msgstr "" -"ハイフンやその他の英数字以外の文字をアンダースコアに正規化するのはなぜですか?" -#: ../source/specifications/platform-compatibility-tags.rst:293 +#: ../source/specifications/inline-script-metadata.rst:214 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)." +"January 2024: Through amendments to :pep:`723`, the ``pyproject`` metadata " +"block type was renamed to ``script``, and the ``[run]`` table was dropped, " +"making the ``dependencies`` and ``requires-python`` keys top-level. " +"Additionally, the specification is no longer provisional." msgstr "" -"ファイル名の部分部分を区分けする ``.`` 文字や ``-`` 文字との干渉を避けるため" -"に、かつ、 (クォートすることなく URL パス内で使用可能であることを含む) 数多あ" -"るファイルシステムのファイル名に対する制限事項との間のより良い互換性のため" -"に。" -#: ../source/specifications/platform-compatibility-tags.rst:305 -msgid "Why not use special character rather than ``.`` or ``-``?" -msgstr "何故、 ``.`` や ``-`` の代わりに特殊な文字 を使わないのですか？" +#: ../source/specifications/name-normalization.rst:3 +#, fuzzy +msgid "Names and normalization" +msgstr "パッケージ名の正規化" -#: ../source/specifications/platform-compatibility-tags.rst:299 +#: ../source/specifications/name-normalization.rst:5 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)." +"This specification defines the format that names for packages and extras are " +"required to follow. It also describes how to normalize them, which should be " +"done before lookups and comparisons." msgstr "" -"それは、その文字が不便であるかコンテクストによっては潜在的に混乱を招きやすい " -"(例えば ``+`` は URL 内ではクォートしなければなりませんし、 ``~`` は POSIX で" -"ユーザのホームディレクトリを示すために使われます) から、あるいは、 :pep:" -"`427` で定義された wheel フォーマットを参照して作成された既存の参照実装を変更" -"すること (例えば、圧縮タグで部分部分を分割するのに ``.`` ではなく ``,`` を使" -"うようにすること) を正当化するに足りるだけのアドバンテージがないから、のいず" -"れかです。" -#: ../source/specifications/platform-compatibility-tags.rst:310 -msgid "Who will maintain the registry of abbreviated implementations?" -msgstr "誰が実装に関する短縮形のレジストリの維持管理をしているのですか？" +#: ../source/specifications/name-normalization.rst:13 +#, fuzzy +msgid "Name format" +msgstr "ファイルフォーマット" -#: ../source/specifications/platform-compatibility-tags.rst:308 +#: ../source/specifications/name-normalization.rst:15 +#, fuzzy 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 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 :py:data:`re.IGNORECASE`)::" msgstr "" -"python-dev メーリングリストで要求することで、新しい２文字省略形の割り当てを受" -"けることができるでしょう。経験上は、その時点で最も卓越した４個の実装のために" -"省略形が予約されています。" +"正当な名前は ASCII 文字・数字・ピリオド・アンダースコア・ハイフンだけで構成さ" +"れているものです。名前の先頭と末尾は文字か数字でなければなりません。正当なプ" +"ロジェクト名は、次の正規表現に (``re.IGNORECASE`` 付きで) マッチするものに限" +"らるということになります::" -#: ../source/specifications/platform-compatibility-tags.rst:315 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" -msgstr "互換性タグは METADATA に含まれるのか、あるいは PKG-INFO か？" +#: ../source/specifications/name-normalization.rst:26 +#, fuzzy +msgid "Name normalization" +msgstr "正規化" -#: ../source/specifications/platform-compatibility-tags.rst:313 +#: ../source/specifications/name-normalization.rst:28 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 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 "" -"否。互換性タグはビルド済み配布物のメタデータの一部です。METADATA / PKG-INFO " -"は、その配布物の単一のビルドではなく配布物の全体にとって正当なものであるべき" -"です。" +"名前は、すべての文字を小文字にして、 ``.`` ・ ``,`` ・ ``_`` の文字が連続で１" +"個以上出現したらそれを単独の ``-`` の文字に置き換えるべきです。これは、 " +"Python の re モジュールを使って実装することができます:" -#: ../source/specifications/platform-compatibility-tags.rst:321 -msgid "Why didn't you mention my favorite Python implementation?" -msgstr "どうして私のお気に入りの Python 実装について言及しなかったの？" +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "次に挙げる名前はすべて同等ということになります:" -#: ../source/specifications/platform-compatibility-tags.rst:318 +#: ../source/specifications/name-normalization.rst:41 +#, fuzzy +msgid "``friendly-bard`` (normalized form)" +msgstr "``friendly-bard`` (正規化形式)" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "``Friendly-Bard``" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "``FRIENDLY-BARD``" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "``friendly.bard``" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "``friendly_bard``" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "``friendly--bard``" + +#: ../source/specifications/name-normalization.rst:47 +#, fuzzy 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 "" -"省略形タグは、コンパイル済みの Python コードを公開のインデックスでシェアする" -"ことを促進します。あなたの Python 実装においてもこの仕様を使うことができます" -"が、しかしもっと長いタグになってしまうことでしょう。すべての \"純 Python\" な" -"ビルド済み配布物が単に ``py`` を使うだけであることを思い出してください。" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "``FrIeNdLy-._.-bArD`` (ひどい書き方の名前の例だが、正当である)" -#: ../source/specifications/platform-compatibility-tags.rst:329 +#: ../source/specifications/name-normalization.rst:52 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"September 2015: The specification of name normalized was approved through :" +"pep:`503 <503#normalized-names>`." msgstr "" -"どうして参照実装における ABI タグ (第２のタグ) は時々 \"none\" なのですか？" -#: ../source/specifications/platform-compatibility-tags.rst:324 +#: ../source/specifications/name-normalization.rst:54 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\"." +"November 2015: The specification of valid names was approved through :pep:" +"`508 <508#names>`." msgstr "" -"Python 2 では SOABI (より新しい版の Python 3 から来た概念) を作成する簡単な方" -"法がないので、本稿執筆時点の参照実装は \"none\" なのです。理想的には、それは" -"もっと新しい版の Python に相似の \"py27(d|m|u)\" を検出するようになるでしょう" -"が、それまでの間は \"知られていない\" ことを示すのに \"none\" とすることが必" -"要十分な方法なのです。" -#: ../source/specifications/platform-compatibility-tags.rst:334 +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "プラットフォームの互換性タグ" + +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"February 2013: The original version of this specification was approved " -"through :pep:`425`." +"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:336 -msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "タグの書式は、 ``{python tag}-{abi tag}-{platform tag}`` です。" -#: ../source/specifications/platform-compatibility-tags.rst:337 -msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "python タグ" -#: ../source/specifications/platform-compatibility-tags.rst:338 -msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "'py27' ・ 'cp33'" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "'cp33dmu' ・ 'none'" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "'linux_x86_64' ・ 'any'" + +#: ../source/specifications/platform-compatibility-tags.rst:25 +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." msgstr "" +"例えば、``py27-none-any`` というタグは、abi に対する要求なしに任意のプラット" +"フォームで Python 2.7 (任意の Python 2.7 実装) との互換性を持つことを意味しま" +"す。" -#: ../source/specifications/platform-compatibility-tags.rst:339 +#: ../source/specifications/platform-compatibility-tags.rst:28 msgid "" -"November 2019: The ``manylinux_x_y`` perennial tag was approved through :pep:" -"`600`." +"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/platform-compatibility-tags.rst:341 -msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" +"どのようなタグであれ、その中に潜在的に含まれる空白文字は ``_`` で置換されるべ" +"きです。" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" -msgstr ":file:`.pypirc` ファイル" +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "Python タグ" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:39 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 Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" 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` パッケージで定義された) フォーマットは:" +"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 "" -"``distutils`` の節では、リポジトリを説明するようなすべての節の名前を列挙する " -"``index-servers`` フィールドを定義しています。" +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "py: 一般的な Python (実装に特有な機能を要求しません)" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" -msgstr "リポジトリを記述する各節では、３個のフィールドを定義しています:" +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "cp: CPython" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." -msgstr "``repository``: リポジトリの URL。" +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "ip: IronPython" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." -msgstr "``username``: リポジトリで登録済みのユーザ名。" +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "pp: PyPy" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." -msgstr "``password``: ユーザ名を認証するために使われるパスワード。" +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "jy: Jython" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/platform-compatibility-tags.rst:48 +#, fuzzy 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 "" -"あなたのパスワードが平文で保存されることに注意してください。より良いセキュリ" -"ティのために `キーリング `_ ・環境変数での設定・コマンドラインでのパ" -"スワード供給のような代替策を検討してください。" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "ほかの Python 実装には ``sys.implementation.name`` を用いるべきです。" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/platform-compatibility-tags.rst:50 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"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 "" -"そうでなければ、 :file:`.pypirc` のパーミッションを設定して、自分だけが閲覧や" -"修正を行えるようにしてください。例えば、 Linux や macOS では次のようにします:" - -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" -msgstr "共通の設定" +"バージョンは ``py_version_nodot`` です。 CPython は no dot にせずに済ませます" +"が、必要な場合には代わりにアンダースコア文字 ``_`` が使用されます。 PyPy は、" +"おそらく、ここに ``pp18`` や ``pp19`` といったそれ自身のバージョンを使いま" +"す。" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/platform-compatibility-tags.rst:54 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." +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -"これらの例は :ref:`twine` に当てはまります。他のプロジェクト (例えば :ref:" -"`flit`) でも :file:`.pypirc` ファイルを利用しますが、デフォルトの値が異なりま" -"す。もっと詳しい情報や使い方の指南については、それぞれのプロジェクトの説明文" -"書を参照してください。" +"多くの純 Python 配布物では、バージョンは ``2`` や ``3`` や ``py2`` ・ " +"``py3`` といったメジャーバージョンだけにしておくことができます。" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:57 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"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 "" -"Twine のデフォルト設定は、 PyPI と TestPyPI のリポジトリ節を含んだ :file:`." -"pypirc` を真似ています:" +"重要なことは、 ``py2`` や ``py3`` のような major-version-only タグは " +"``py20`` や ``py30`` の短縮形であるわけではないということです。そうではなく" +"て、これらのタグは、パッケージ作成者がいくつものバージョンに互換性を持つ配布" +"物を意図的にリリースしたのです。" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/platform-compatibility-tags.rst:61 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -"Twine は、 :file:`$HOME/.pypirc` からの設定に対して、コマンドラインや環境変数" -"といった追加の設定をデフォルト設定に追加するでしょう。" +"単一ソースで Python 2/3 に互換性を持つ配布物は、合成タグ ``py2.py3`` を用いる" +"ことができます。 後述の `タグの圧縮された組み合わせ `_ " +"を参照してください。" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" -msgstr "PyPI トークンを使う" +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "ABI タグ" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/platform-compatibility-tags.rst:68 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"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 "" -"自分の PyPI 用 `API トークン`_ を設定するには、次のような :file:`$HOME/." -"pypirc` を作れば良いでしょう:" +"ABI タグは、いずれかの拡張モジュールによってどのような Python ABI が要求され" +"ているのかを示します。実装依存の ABI 群については、実装 (の名前) は、たとえ" +"ば ``cp33d`` がデバッグオプション付きの CPython 3.3 ABI のことを指すように、 " +"Python タグと同様のやり方で短縮したものを使います。" -#: ../source/specifications/pypirc.rst:96 -msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -":ref:`TestPyPI ` 用には、Test PyPI アカウントで作成した API" -"トークンを使った ``[testpypi]`` 節を追加してください。" - -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" -msgstr "別のパッケージインデックスを使う" +"CPython の安定版 ABI のことは、共有ライブラリの拡張子と同様に ``abi3`` と書き" +"ます。" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/platform-compatibility-tags.rst:75 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:" +"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 "" -"追加のリポジトリの設定を行うには、 ``index-servers`` フィールドにそのリポジト" -"リの名前が含まれるように再定義する必要があるでしょう。PyPI と TestPyPI とプラ" -"イベートなリポジトリの設定をした :file:`$HOME/.pypirc` の完全な例を示します:" +"非常に不安定な ABI を持つ実装は、そのソースコードのリビジョンやコンパイラフラ" +"グその他の SHA-256 ハッシュ値の最初の６バイトを (BASE64にエンコードされた８文" +"字として) 用いても構いませんが、おそらくはバイナリ配布物を配布することには大" +"きな需要はないでしょう。それぞれの実装のコミュニティで ABI タグをどのように用" +"いるのが最適かを決定すればよいでしょう。" -#: ../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 "" -"``password`` フィールドを使う代わりに、 (Twineによってインストールされる) `" -"キーリング `_ を使って API トークンやパスワードを安全に保存すること" -"を検討してください:" +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "プラットフォームタグ" -#: ../source/specifications/pyproject-toml.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:86 #, fuzzy -msgid "``pyproject.toml`` specification" -msgstr "``pyproject.toml`` は必須ですか？" +msgid "Basic platform tags" +msgstr "プラットフォームタグ" -#: ../source/specifications/pyproject-toml.rst:10 +#: ../source/specifications/platform-compatibility-tags.rst:88 +#, fuzzy msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"In its simplest form, the platform tag is :py:func:`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 example:" msgstr "" +"プラットフォームタグは、すべてのハイフン ``-`` とピリオド ``.`` をアンダース" +"コア ``_`` で単純に置き換えた ``sysconfig.get_platform()`` です。 :ref:" +"`distutils` が Python 3.12 で削除されるまでは、これは ``distutils.util." +"get_platform()`` でした。" -#: ../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:93 +msgid "win32" +msgstr "win32" -#: ../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:94 +msgid "linux_i386" +msgstr "linux_i386" -#: ../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:95 +msgid "linux_x86_64" +msgstr "linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "``manylinux``" +msgstr "``manylinux``" -#: ../source/specifications/pyproject-toml.rst:29 +#: ../source/specifications/platform-compatibility-tags.rst:103 #, fuzzy -msgid "Declaring build system dependencies: the ``[build-system]`` table" -msgstr "ビルドシステムの依存関係を宣言する" +msgid "" +"The simple scheme above is insufficient for public distribution of wheel " +"files 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/pyproject-toml.rst:31 +#: ../source/specifications/platform-compatibility-tags.rst:107 #, 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." +"Instead, for those platforms, the ``manylinux`` standard 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 "" -"`pyproject.toml` は :pep:`518` で定義されたビルドシステムとは独立したファイル" -"形式で、あるプロジェクトのビルドシステムが正常に動作するためにインストールさ" -"れていなければならない Python レベルの依存関係をすべて宣言するという目的のた" -"めにそのプロジェクトが提供するものです。" +"代わりに、 :pep:`600` で Linux プラットフォームの共通のサブセットを表現する" +"``manylinux`` 標準が定義されており、普通の Linux ディストロのほとんどで使え" +"る ``manylinux`` プラットフォームタグ付きの wheel をビルドできるようにしてい" +"ます。" -#: ../source/specifications/pyproject-toml.rst:37 +#: ../source/specifications/platform-compatibility-tags.rst:112 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 current standard is the future-proof ``manylinux_x_y`` standard. It " +"defines tags of the form ``manylinux_x_y_arch``, where ``x`` and ``y`` are " +"glibc major and minor versions supported (e.g. ``manylinux_2_24_xxx`` should " +"work on any distro using glibc 2.24+), and ``arch`` is the architecture, " +"matching the value of :py:func:`sysconfig.get_platform()` on the system as " +"in the \"simple\" form above." msgstr "" -#: ../source/specifications/pyproject-toml.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:118 msgid "" -"An example ``[build-system]`` table for a project built with ``setuptools`` " -"is:" +"The following older tags are still supported for backward compatibility:" msgstr "" -#: ../source/specifications/pyproject-toml.rst:53 +#: ../source/specifications/platform-compatibility-tags.rst:120 +#, fuzzy msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." msgstr "" +"``manylinux1`` (:pep:`513`) は、 ``x86_64`` および ``i686`` アーキテクチャを" +"サポートしていて、 2007 年から互換性のある Linux プラットフォームに基づいてい" +"ます。" -#: ../source/specifications/pyproject-toml.rst:56 -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/platform-compatibility-tags.rst:121 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." msgstr "" -#: ../source/specifications/pyproject-toml.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:122 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:" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." msgstr "" -#: ../source/specifications/pyproject-toml.rst:103 -#, fuzzy -msgid "Declaring project metadata: the ``[project]`` table" -msgstr "プロジェクトのメタデータを宣言する" - -#: ../source/specifications/pyproject-toml.rst:105 +#: ../source/specifications/platform-compatibility-tags.rst:125 msgid "" -"The ``[project]`` table specifies the project's :ref:`core metadata `." +"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/pyproject-toml.rst:107 +#: ../source/specifications/platform-compatibility-tags.rst:131 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." +"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 "" -"メタデータにはふたつの種類があります: *静的* なものと *動的* なものです。静的" -"なメタデータは ``pyproject.toml`` ファイルで直接指定されていて、ツール側では" -"指定したり変更したりできません (これは、例えばメタデータが参照するファイルの" -"内容のような、メタデータによって *参照* されるデータを含みます)。動的なメタ" -"データは ``dynamic`` キー (この仕様内で後で定義します) を経由して一覧化されて" -"いて、ツール側が後から提供することになるでしょう。" +"``manylinux1`` と ``manylinux2010`` は既に end-of-life に達していて、提供され" +"ているビルド環境にはもはやセキュリティアップデートが提供されることはないであ" +"ろうという警告されていることもあって、パッケージ保守者は最も互換性のある仕様" +"をターゲットにするように努力するべきです。" -#: ../source/specifications/pyproject-toml.rst:115 +#: ../source/specifications/platform-compatibility-tags.rst:136 msgid "" -"The lack of a ``[project]`` table implicitly means the :term:`build backend " -"` will dynamically provide all keys." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" +"適切なプロジェクトがサポートするさまざまな ``manylinux`` 標準の最低限のバー" +"ジョンを次に掲げる表に示します:" -#: ../source/specifications/pyproject-toml.rst:118 -msgid "The only keys required to be statically defined are:" -msgstr "必ず静的に定義しなければならない必須のキーは次の通り:" +#: ../source/specifications/platform-compatibility-tags.rst:140 +msgid "Tool" +msgstr "ツール" -#: ../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:140 +msgid "``manylinux1``" +msgstr "``manylinux1``" -#: ../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:140 +msgid "``manylinux2010``" +msgstr "``manylinux2010``" -#: ../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:140 +msgid "``manylinux2014``" +msgstr "``manylinux2014``" -#: ../source/specifications/pyproject-toml.rst:132 -msgid "``authors``" -msgstr "``著者 ``" +#: ../source/specifications/platform-compatibility-tags.rst:140 +msgid "``manylinux_x_y``" +msgstr "``manylinux_x_y``" -#: ../source/specifications/pyproject-toml.rst:134 -msgid "``dependencies``" -msgstr "``依存関係 =8.1.0``" +msgstr "``>=8.1.0``" -#: ../source/specifications/pyproject-toml.rst:136 -#: ../source/specifications/pyproject-toml.rst:384 -msgid "``dynamic``" -msgstr "``dynamic``" +#: ../source/specifications/platform-compatibility-tags.rst:142 +msgid "``>=19.0``" +msgstr "``>=19.0``" -#: ../source/specifications/pyproject-toml.rst:137 -msgid "``entry-points``" -msgstr "``entry-points``" +#: ../source/specifications/platform-compatibility-tags.rst:142 +msgid "``>=19.3``" +msgstr "``>=19.3``" -#: ../source/specifications/pyproject-toml.rst:138 -msgid "``gui-scripts``" -msgstr "``gui スクリプト ``" +#: ../source/specifications/platform-compatibility-tags.rst:142 +msgid "``>=20.3``" +msgstr "``>=20.3``" -#: ../source/specifications/pyproject-toml.rst:141 -msgid "``maintainers``" -msgstr "``保守者 ``" +#: ../source/specifications/platform-compatibility-tags.rst:143 +msgid "auditwheel" +msgstr "auditwheel" -#: ../source/specifications/pyproject-toml.rst:143 -msgid "``optional-dependencies``" -msgstr "``optional-dependencies``" +#: ../source/specifications/platform-compatibility-tags.rst:143 +msgid "``>=1.0.0``" +msgstr "``>=1.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 "TOML_ 型: 文字列" +#: ../source/specifications/platform-compatibility-tags.rst:143 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" -#: ../source/specifications/pyproject-toml.rst:155 +#: ../source/specifications/platform-compatibility-tags.rst:143 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:143 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:146 +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/platform-compatibility-tags.rst:150 +#, fuzzy +msgid "``musllinux``" +msgstr "``manylinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"The ``musllinux`` family of tags is similar to ``manylinux``, but for Linux " +"platforms that use the musl_ libc rather than glibc (a prime example being " +"Alpine Linux). The schema is ``musllinux_x_y_arch``, supporting musl ``x.y`` " +"and higher on the architecture ``arch``." msgstr "" -":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`名前 " -"` フィールド" -#: ../source/specifications/pyproject-toml.rst:158 -msgid "The name of the project." -msgstr "プロジェクトの名前。" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The musl version values can be obtained by executing the musl libc shared " +"library the Python interpreter is currently running on, and parsing the " +"output:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:188 +msgid "" +"There are currently two possible ways to find the musl library’s location " +"that a Python interpreter is running on, either with the system ldd_ " +"command, or by parsing the ``PT_INTERP`` section’s value from the " +"executable’s ELF_ header." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:194 +msgid "Use" +msgstr "使い方" -#: ../source/specifications/pyproject-toml.rst:160 +#: ../source/specifications/platform-compatibility-tags.rst:196 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"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 "" -"内部的な一貫性を保つために、ツール側では読み取ったらすぐに、この名前を :ref:`" -"正規化 ` するべきです。" +"タグ類は、 (もしダウンロードが必要なら) 選択可能なビルド済配布物のリストの中" +"からどれをダウンロードするのかをインストーラが決定するために使われます。イン" +"ストーラは、自身がサポートする (pyver, abi, arch) タプルのリストを維持管理し" +"ています。ビルド済配布物のタグがリストに含まれて (``in`` ) いれば、それをイン" +"ストールすることができます。" -#: ../source/specifications/pyproject-toml.rst:167 +#: ../source/specifications/platform-compatibility-tags.rst:202 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"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 "" -":ref:`コアとなるメタデータ ` に対応する: :ref:`バージョン " -"`" +"古い Python リリース向けに発行された純 Python のバージョンにフォールバックす" +"るよりも前に、利用できる中で最も機能を網羅したビルド済配布物 (インストールす" +"る先の環境に最も適したもの) をインストーラがデフォルトで選択することが推奨さ" +"れています。インストーラは、また、受け入れ可能な互換性タグのリストを設定変更" +"したり順序を入れ替えたりする方法を持つことが推奨されています; 例えば、ユーザ" +"は、純 Python であると広報しているビルド済みパッケージだけをダウンロードする" +"ために、 ``*-none-any`` タグだけを受容しても構いません。" -#: ../source/specifications/pyproject-toml.rst:170 +#: ../source/specifications/platform-compatibility-tags.rst:210 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"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/pyproject-toml.rst:173 -msgid "Users SHOULD prefer to specify already-normalized versions." -msgstr "ユーザは正規化済みのバージョンを指定するようにするべきです。" - -#: ../source/specifications/pyproject-toml.rst:180 +#: ../source/specifications/platform-compatibility-tags.rst:214 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"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 "" -":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`要約 " -"`" +"この事例集は、インストーラを linux_x86_64 システム上の CPython 3.3 のもとで走" +"らせるためのものです。最も好ましいもの (最新版の Python 向けにビルドされたコ" +"ンパイル済みの拡張モジュールが付属している配布物) から、最も好ましくはないも" +"の (古いバージョンの Python でビルドされた純 Python の配布物) へ、という順序" +"で並んでいます:" -#: ../source/specifications/pyproject-toml.rst:183 -msgid "The summary description of the project." -msgstr "プロジェクトを要約する記述。" +#: ../source/specifications/platform-compatibility-tags.rst:220 +msgid "cp33-cp33m-linux_x86_64" +msgstr "cp33-cp33m-linux_x86_64" -#: ../source/specifications/pyproject-toml.rst:189 -msgid "TOML_ type: string or table" -msgstr "TOML_ 型: 文字列またはテーブル" +#: ../source/specifications/platform-compatibility-tags.rst:221 +msgid "cp33-abi3-linux_x86_64" +msgstr "cp33-abi3-linux_x86_64" -#: ../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/platform-compatibility-tags.rst:222 +msgid "cp3-abi3-linux_x86_64" +msgstr "cp3-abi3-linux_x86_64" -#: ../source/specifications/pyproject-toml.rst:194 -msgid "The full description of the project (i.e. the README)." -msgstr "プロジェクトの説明全体 (すなわち README)。" +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "cp33-none-linux_x86_64*" +msgstr "cp33-none-linux_x86_64*" -#: ../source/specifications/pyproject-toml.rst:196 +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "cp3-none-linux_x86_64*" +msgstr "cp3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "py33-none-linux_x86_64*" +msgstr "py33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "py3-none-linux_x86_64*" +msgstr "py3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "cp33-none-any" +msgstr "cp33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "cp3-none-any" +msgstr "cp3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "py33-none-any" +msgstr "py33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "py3-none-any" +msgstr "py3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:231 +msgid "py32-none-any" +msgstr "py32-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:232 +msgid "py31-none-any" +msgstr "py31-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "py30-none-any" +msgstr "py30-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:235 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." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -"このキーは文字列かテーブルを受け付けます。もし文字列なら、完全な説明を含むテ" -"キストファイルの位置を ``pyproject.toml`` からの相対パスで示したものです。" -"ツールの側ではこのファイルが UTF-8 でエンコードされているものと想定しなければ" -"なりません。ファイルパスが大文字小文字を問わず ``.md`` 拡張子で終わっている場" -"合は、ツールはそのファイルの content-type が ``text/markdown`` であるものと仮" -"定しなければなりません。ファイルパスが大文字小文字を問わず ``.rst`` で終わっ" -"ている場合は、ツールは content-type が ``text/x-rst`` であるものと仮定しなけ" -"ればなりません。この PEP で指定するよりも多くの拡張子をツールが認識するなら、" -"そのようなツールは、このキーを ``dynamic`` であると指定していなくても、ユーザ" -"のために content-type を推測しても構いません。content-type が与えられていない" -"場合には、全ての認識できない拡張子についてツールはエラーを発生させなければな" -"りません。" +"ビルド済み配布物は、サブプロセスとして起動されるネーティブの実行可能ファイル" +"を含んでいるなどのようなC 言語拡張以外の理由によって、特定のプラットフォーム" +"向けであっても構いません。" -#: ../source/specifications/pyproject-toml.rst:207 +#: ../source/specifications/platform-compatibility-tags.rst:239 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." +"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 "" -"``readme`` キーはその値がテーブルでも構いません。 ``file`` キーは、完全な説明" -"を含むファイルへの ``pyproject.toml`` ファイルからの相対パスを表現する文字列" -"を値として持ちます。 ``text`` キーは、完全な説明そのものである文字列を値に持" -"ちます。これらのキーは排他的にいずれかひとつしか使えないので、もしメタデータ" -"がこれら両方のキーを同時に指定していたらツールはエラーを発生させなければなり" -"ません。" +"時々、あるパッケージの特定のバージョンとして複数のビルド済み配布物が存在する" +"ことがあるでしょう。例えば、パッケージ製作者が、 ``cp33-abi3-linux_x86_64`` " +"というタグを付けて追加的な C 言語拡張を含むパッケージをリリースし、そのような" +"ものを含まない同じ配布物に ``py3-none-any`` というタグを付けてリリースするよ" +"うな場合です。(このような場合でも) サポートされるタグのリストで先に出現する方" +"を優先するという理由によって C 言語拡張付きのパッケージがそうでないパッケージ" +"よりも選好されてインストールされるという形で、インデックスによってどちらかに" +"決めることができます。" -#: ../source/specifications/pyproject-toml.rst:214 +#: ../source/specifications/platform-compatibility-tags.rst:248 +msgid "Compressed Tag Sets" +msgstr "圧縮されたタグのセット" + +#: ../source/specifications/platform-compatibility-tags.rst:250 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." +"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 "" -"``readme`` キーに指定されたテーブルには、完全な説明の content-type を指定する" -"文字列を値とする ``content-type`` キーも含まれています。メタデータがこのキー" -"をテーブルの中で指定していない場合には、ツールはエラーを発生させなければなり" -"ません。メタデータで ``charset`` パラメータが指定されていない場合には、 " -"UTF-8 であるものと想定されます。ツールは各ツールが独自に選択した他のエンコー" -"ディングをサポートしても構いません。 :ref:`コアとなるメタデータ ` によってサポートされている content-type に変換することができるので" -"あれば、ツールはそのような代替 content-type をサポートしても構いません。そう" -"でなければ、ツールはサポートしていない content-type に対してエラーを発生させ" -"なければなりません。" +"bdists のコンパクトなファイル名で、互換性のあるタグトリプルが複数ある場合にも" +"きちんと動作するものを許容するためには、代わりにファイル名の中のそれぞれのタ" +"グが '.' で分割可能でありソート可能であるような一連のタグになっていることが可" +"能です。例えば、 pip は純 Python のパッケージで、同一のソースコードで Python " +"2 でも 3 でも動作するように書かれていますが、これは ``py2.py3-none-any`` とい" +"うタグを付けた bdist として配布することができるでしょう。単純なタグの完全なリ" +"ストは::" -#: ../source/specifications/pyproject-toml.rst:229 +#: ../source/specifications/platform-compatibility-tags.rst:262 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +"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 "" -":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:" -"`Requires-Python `" +"このスキームを実装する bdist フォーマットは、拡張されたタグ群を bdist に特有" +"のメタデータの中に含んでいるべきです。この圧縮スキームは、サポートされていな" +"いタグや例えば \"cp33-cp31u-win64\" のようにいかなる Python 実装においてもサ" +"ポートされていない \"不可能な\" タグを大量に生成すると思われるので、控えめに" +"使うようにしてください。" -#: ../source/specifications/pyproject-toml.rst:232 -msgid "The Python version requirements of the project." -msgstr "プロジェクトが要求する Python のバージョン。" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "What tags are used by default?" +msgstr "デフォルトではどんなタグが使われますか？" -#: ../source/specifications/pyproject-toml.rst:238 -msgid "TOML_ type: table" -msgstr "TOML_ 型: テーブル" +#: ../source/specifications/platform-compatibility-tags.rst:271 +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 "" +"ツール類は、 ``cp33-cp33m-win32`` のようなアーキテクチャへの依存を示すタグや " +"``py33-none-any`` のような純 Python タグの中で最も好ましいものをデフォルトで" +"採用するべきです。パッケージ製作者がデフォルトをオーバーライドしていたとすれ" +"ば、それは彼らが異なる Python 間での互換性を提供しようという意図があったこと" +"を示しています。" -#: ../source/specifications/pyproject-toml.rst:239 +#: ../source/specifications/platform-compatibility-tags.rst:285 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`License `" +"自分の配布物が最新版の Python と相容れない機能を使っているとしたら、どんなタ" +"グを使いますか？" -#: ../source/specifications/pyproject-toml.rst:242 +#: ../source/specifications/platform-compatibility-tags.rst:278 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." +"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 "" -"テーブルには二つのキーのうちのいずれか一つを書くことができます。 ``file`` " -"キーは、 ``pyproject.toml`` からプロジェクトのライセンス情報を含むファイルへ" -"の相対パスを値とする文字列です。ツールの側では、そのファイルのエンコーディン" -"グが UTF-8 であるものと仮定しなければなりません。 ``text`` キーは、プロジェク" -"トのライセンス条項そのものである文字列を値に取ります。これらのキーは相互に排" -"他的で、従って、両方のキーが指定されているメタデータについてツールの側ではエ" -"ラーを発生させなければなりません。" +"互換性タグは、インストーラがある配布物の *単一のバージョン* の *最も互換性が" +"ある* ビルドを選択する際に助けとなります。例えば、 (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/pyproject-toml.rst:253 -msgid "TOML_ type: Array of inline tables with string keys and values" -msgstr "TOML_ 型: 文字列のキー・バリュー組を伴ったインラインテーブルの配列" +#: ../source/specifications/platform-compatibility-tags.rst:290 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "Python のバージョン番号に ``.`` がないのはなぜですか?" -#: ../source/specifications/pyproject-toml.rst:254 +#: ../source/specifications/platform-compatibility-tags.rst:288 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +"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 "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Author ` ・ :ref:`Author-email ` ・ :ref:`Maintainer ` ・ :ref:`Maintainer-" -"email `" +"CPython は、数字３個のメジャーリリースなしで 20 年以上にわたって存続してきま" +"した。これはしばらくの間は続くに違いありません。 - や . が周辺のファイル名を" +"区切る役割を果たしているので、他の実装では _ を区切り子として使っても構いませ" +"ん。" -#: ../source/specifications/pyproject-toml.rst:260 +#: ../source/specifications/platform-compatibility-tags.rst:296 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." +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -"プロジェクトの \"作者\" であると考えられる人々ないし組織。正確な意味はさまざ" -"まに解釈可能です — 元々のまたは主要な作者でも構わないし、現在の保守者やパッ" -"ケージのオーナでも構いません。" +"ハイフンやその他の英数字以外の文字をアンダースコアに正規化するのはなぜですか?" -#: ../source/specifications/pyproject-toml.rst:265 +#: ../source/specifications/platform-compatibility-tags.rst:293 msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +"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 "" -"\"maintainers\" キーは \"authors\" キーに似ていて、その正確な意味はさまざまに" -"解釈可能です。" +"ファイル名の部分部分を区分けする ``.`` 文字や ``-`` 文字との干渉を避けるため" +"に、かつ、 (クォートすることなく URL パス内で使用可能であることを含む) 数多あ" +"るファイルシステムのファイル名に対する制限事項との間のより良い互換性のため" +"に。" -#: ../source/specifications/pyproject-toml.rst:268 +#: ../source/specifications/platform-compatibility-tags.rst:305 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "何故、 ``.`` や ``-`` の代わりに特殊な文字 を使わないのですか？" + +#: ../source/specifications/platform-compatibility-tags.rst:299 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." +"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 "" -"これらのキーは、 ``name`` と ``email`` のふたつのキーを伴ったテーブルの配列を" -"受け入れます。両方の値は文字列でなければなりません。 ``name`` の値は、電子" -"メールアドレスにおける正当な名前 (すなわち、 :rfc:`822` における電子メールア" -"ドレスのアドレス部分に前置できる名前なら何でも可) で、コンマを含まないもので" -"なければなりません。 ``email`` の値は、正当な電子メールアドレスでなければなり" -"ません。これらのキーは共に必須ではありませんが、少なくともいずれかのキーが" -"テーブル内で指定されていなければなりません。" +"それは、その文字が不便であるかコンテクストによっては潜在的に混乱を招きやすい " +"(例えば ``+`` は URL 内ではクォートしなければなりませんし、 ``~`` は POSIX で" +"ユーザのホームディレクトリを示すために使われます) から、あるいは、 :pep:" +"`427` で定義された wheel フォーマットを参照して作成された既存の参照実装を変更" +"すること (例えば、圧縮タグで部分部分を分割するのに ``.`` ではなく ``,`` を使" +"うようにすること) を正当化するに足りるだけのアドバンテージがないから、のいず" +"れかです。" -#: ../source/specifications/pyproject-toml.rst:275 +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "誰が実装に関する短縮形のレジストリの維持管理をしているのですか？" + +#: ../source/specifications/platform-compatibility-tags.rst:308 msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +"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 "" -"データを使って :ref:`コアとなるメタデータ ` に書き込むやり方は" -"次の通りです:" +"python-dev メーリングリストで要求することで、新しい２文字省略形の割り当てを受" +"けることができるでしょう。経験上は、その時点で最も卓越した４個の実装のために" +"省略形が予約されています。" -#: ../source/specifications/pyproject-toml.rst:278 +#: ../source/specifications/platform-compatibility-tags.rst:315 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "互換性タグは METADATA に含まれるのか、あるいは PKG-INFO か？" + +#: ../source/specifications/platform-compatibility-tags.rst:313 msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +"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 "" -"``name`` だけが与えられた場合には、その値を :ref:`Author ` なり :ref:`Maintainer ` なりに書き込みま" -"す。" +"否。互換性タグはビルド済み配布物のメタデータの一部です。METADATA / PKG-INFO " +"は、その配布物の単一のビルドではなく配布物の全体にとって正当なものであるべき" +"です。" -#: ../source/specifications/pyproject-toml.rst:281 +#: ../source/specifications/platform-compatibility-tags.rst:321 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "どうして私のお気に入りの Python 実装について言及しなかったの？" + +#: ../source/specifications/platform-compatibility-tags.rst:318 msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +"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 "" -"``email`` だけの場合には、その値を :ref:`Author-email ` なり :ref:`Maintainer-email ` なりに" -"書き込みます。" +"省略形タグは、コンパイル済みの Python コードを公開のインデックスでシェアする" +"ことを促進します。あなたの Python 実装においてもこの仕様を使うことができます" +"が、しかしもっと長いタグになってしまうことでしょう。すべての \"純 Python\" な" +"ビルド済み配布物が単に ``py`` を使うだけであることを思い出してください。" -#: ../source/specifications/pyproject-toml.rst:285 +#: ../source/specifications/platform-compatibility-tags.rst:329 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}>``." +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" 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_ 型: 文字列の配列" +"どうして参照実装における ABI タグ (第２のタグ) は時々 \"none\" なのですか？" -#: ../source/specifications/pyproject-toml.rst:296 +#: ../source/specifications/platform-compatibility-tags.rst:324 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +"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 "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Keywords ` field: :ref:`Classifier " -"`" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Classifier `" -#: ../source/specifications/pyproject-toml.rst:309 -msgid "Trove classifiers which apply to the project." -msgstr "プロジェクトに適合する Trove 分類子。" +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" -#: ../source/specifications/pyproject-toml.rst:315 -msgid "TOML_ type: table with keys and values of strings" -msgstr "TOML_ 型: 文字列のキー・バリューを伴うテーブル" +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" -#: ../source/specifications/pyproject-toml.rst:316 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Project-URL `" -#: ../source/specifications/pyproject-toml.rst:319 +#: ../source/specifications/platform-compatibility-tags.rst:339 msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +"November 2019: The ``manylinux_x_y`` perennial tag was approved through :pep:" +"`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." msgstr "" -"URL のテーブルで、 URL に付けられたラベルがキーで URL そのものが値になってい" -"るもの。" -#: ../source/specifications/pyproject-toml.rst:324 -msgid "Entry points" -msgstr "エントリポイント" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr ":file:`.pypirc` ファイル" -#: ../source/specifications/pyproject-toml.rst:326 +#: ../source/specifications/pypirc.rst:8 msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +"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 "" -"TOML_ 型: table (``[project.scripts]`` ・ ``[project.gui-scripts]`` ・ " -"``[project.entry-points]``)" +":file:`.pypirc` ファイルを使うと、 :term:`パッケージインデックス ` (ここでは \"リポジトリ\" と呼びます) 向けの設定を定義しておけば、 :" +"ref:`twine` や :ref:`flit` でパッケージをアップロードする際に URL ・ユーザ" +"名・パスワードなどの入力を省くことができます。" -#: ../source/specifications/pyproject-toml.rst:328 -msgid ":ref:`Entry points specification `" -msgstr ":ref:`Entry points specification `" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "(元々は :ref:`distutils` パッケージで定義された) フォーマットは:" -#: ../source/specifications/pyproject-toml.rst:330 +#: ../source/specifications/pypirc.rst:32 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." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -"みっつのテーブルがエントリポイントに関係しています。 ``[project.scripts]`` " -"テーブルは、 :ref:`エントリポイント仕様 ` の中の " -"``console_scripts`` グループに対応しています。テーブル内のキーはエントリポイ" -"ントの名前であり、値は参照されるオブジェクトです。" +"``distutils`` の節では、リポジトリを説明するようなすべての節の名前を列挙する " +"``index-servers`` フィールドを定義しています。" -#: ../source/specifications/pyproject-toml.rst:336 +#: ../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``: ユーザ名を認証するために使われるパスワード。" + +#: ../source/specifications/pypirc.rst:43 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]``." +"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 "" -"``[project.gui-scripts]`` テーブルは、 :ref:`エントリポイント仕様 ` の中の ``gui_scripts`` グループに対応します。そのフォーマットは " -"``[project.scripts]`` と同じです。" +"あなたのパスワードが平文で保存されることに注意してください。より良いセキュリ" +"ティのために `キーリング `_ ・環境変数での設定・コマンドラインでのパ" +"スワード供給のような代替策を検討してください。" -#: ../source/specifications/pyproject-toml.rst:340 +#: ../source/specifications/pypirc.rst:47 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." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -"``[project.entry-points]`` テーブルは、テーブルの集合体です。それぞれのサブ" -"テーブルの名前は、ひとつのエントリポイントグループです。キーと値の意味すると" -"ころは ``[project.scripts]`` と同じです。ユーザはネストしたサブテーブルを作っ" -"てはならず、代わりにエントリポイントグループを１段階の深さに保つようにしなけ" -"ればなりません。" +"そうでなければ、 :file:`.pypirc` のパーミッションを設定して、自分だけが閲覧や" +"修正を行えるようにしてください。例えば、 Linux や macOS では次のようにします:" -#: ../source/specifications/pyproject-toml.rst:346 +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" +msgstr "共通の設定" + +#: ../source/specifications/pypirc.rst:61 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." +"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 "" -"メタデータの中に ``[project.entry-points.console_scripts]`` もしくは " -"``[project.entry-points.gui_scripts]`` というテーブルが定義されている場合は、" -"それぞれ ``[project.scripts]`` や ``[project.gui-scripts]`` と混同してしまう" -"といけないので、ビルド時のバックエンドがエラーを発生させなければなりません。" +"これらの例は :ref:`twine` に当てはまります。他のプロジェクト (例えば :ref:" +"`flit`) でも :file:`.pypirc` ファイルを利用しますが、デフォルトの値が異なりま" +"す。もっと詳しい情報や使い方の指南については、それぞれのプロジェクトの説明文" +"書を参照してください。" -#: ../source/specifications/pyproject-toml.rst:356 +#: ../source/specifications/pypirc.rst:65 msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -"TOML_ 型: :pep:`508` の文字列 (``dependencies``) の配列、および、 :pep:`508` " -"の文字列 (``optional-dependencies``) の配列の値を伴ったテーブル" +"Twine のデフォルト設定は、 PyPI と TestPyPI のリポジトリ節を含んだ :file:`." +"pypirc` を真似ています:" -#: ../source/specifications/pyproject-toml.rst:359 +#: ../source/specifications/pypirc.rst:81 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Requires-Dist ` および :ref:`Provides-Extra " -"`" +"Twine は、 :file:`$HOME/.pypirc` からの設定に対して、コマンドラインや環境変数" +"といった追加の設定をデフォルト設定に追加するでしょう。" -#: ../source/specifications/pyproject-toml.rst:363 -msgid "The (optional) dependencies of the project." -msgstr "(必須ではない) プロジェクトの依存関係。" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" +msgstr "PyPI トークンを使う" -#: ../source/specifications/pyproject-toml.rst:365 +#: ../source/specifications/pypirc.rst:87 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." +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -"``dependencies`` には、文字列の配列が値であるようなキーです。それぞれの文字列" -"がそのプロジェクトの依存関係を表現していて、正当な :pep:`508` の文字列として" -"フォーマットされていなければなりません。それぞれの文字列は、 :ref:`Requires-" -"Dist ` エントリに直接にマップしています。" +"自分の PyPI 用 `API トークン`_ を設定するには、次のような :file:`$HOME/." +"pypirc` を作れば良いでしょう:" -#: ../source/specifications/pyproject-toml.rst:370 +#: ../source/specifications/pypirc.rst:96 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." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -"``optional-dependencies`` は、それぞれのキーが追加物で、その値が文字列の配列" -"であるようなテーブルです。文字列の配列は正当な :pep:`508` の文字列でなければ" -"なりません。キーは :ref:`Provides-Extra ` とし" -"てみた時に正当な値でなければなりません。従って、配列の中のそれぞれの値は、一" -"致する :ref:`Provides-Extra ` メタデータに対応" -"する :ref:`Requires-Dist ` のエントリになりま" -"す。" +":ref:`TestPyPI ` 用には、Test PyPI アカウントで作成した API" +"トークンを使った ``[testpypi]`` 節を追加してください。" -#: ../source/specifications/pyproject-toml.rst:386 -msgid "TOML_ type: array of string" -msgstr "TOML_ 型: 文字列の配列" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" +msgstr "別のパッケージインデックスを使う" -#: ../source/specifications/pyproject-toml.rst:387 +#: ../source/specifications/pypirc.rst:104 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +"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 "" -":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`ダイ" -"ナミック ` フィールド" +"追加のリポジトリの設定を行うには、 ``index-servers`` フィールドにそのリポジト" +"リの名前が含まれるように再定義する必要があるでしょう。PyPI と TestPyPI とプラ" +"イベートなリポジトリの設定をした :file:`$HOME/.pypirc` の完全な例を示します:" -#: ../source/specifications/pyproject-toml.rst:390 +#: ../source/specifications/pypirc.rst:131 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." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -"この PEP に列挙されたキーのどれを意図的に指定しないままにすることで他のツール" -"が動的にそのようなメタデータを準備することができる/しようとするかを規定しま" -"す。後述するツールによる設定に比較して、どのメタデータが目的を持って未指定に" -"されていて未指定のままであることを期待されているのかについて明確に描き出しま" -"す。" +"``password`` フィールドを使う代わりに、 (Twineによってインストールされる) `" +"キーリング `_ を使って API トークンやパスワードを安全に保存すること" +"を検討してください:" -#: ../source/specifications/pyproject-toml.rst:396 +#: ../source/specifications/pyproject-toml.rst:6 +#, fuzzy +msgid "``pyproject.toml`` specification" +msgstr "``pyproject.toml`` は必須ですか？" + +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -"ビルド用のバックエンドは、静的に指定されたメタデータ (つまり ``dynamic`` 内に" -"列挙されたキーではないメタデータ) を尊重しなければなりません。" -#: ../source/specifications/pyproject-toml.rst:398 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -"メタデータで ``dynamic`` 内に ``name`` が指定されている場合には、ビルド用バッ" -"クエンドがエラーを発生させなければなりません。" -#: ../source/specifications/pyproject-toml.rst:400 +#: ../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 "" -"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 ``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 "" -":ref:`コアとなるメタデータ ` の仕様において、あるキーが \"必須" -"である\" ものとして挙げられている場合には、メタデータはそのキーを静的に指定す" -"るか、または、 ``dynamic`` 内に指定するかしなければなりません (どちらでもない" -"場合にはビルドバックエンドがエラーを発生させなければなりません、すなわち、必" -"須のフィールドが ``[project]`` テーブルの中にどんな形でも存在していないという" -"ことは不可能であるべきです)。" -#: ../source/specifications/pyproject-toml.rst:405 +#: ../source/specifications/pyproject-toml.rst:29 +#, fuzzy +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "ビルドシステムの依存関係を宣言する" + +#: ../source/specifications/pyproject-toml.rst:31 +#, fuzzy 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 ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -":ref:`コアとなるメタデータ ` の仕様で、あるキーを \"必須ではな" -"い\" ものとして挙げている場合には、後でビルド用バックエンドがそのキー用のデー" -"タを提供するという期待が持てるのであればメタデータではそのキーを ``dynamic`` " -"の中に挙げても構いません。" +"`pyproject.toml` は :pep:`518` で定義されたビルドシステムとは独立したファイル" +"形式で、あるプロジェクトのビルドシステムが正常に動作するためにインストールさ" +"れていなければならない Python レベルの依存関係をすべて宣言するという目的のた" +"めにそのプロジェクトが提供するものです。" -#: ../source/specifications/pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"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 "" -"メタデータ内で、あるキーが静的に指定されていて、かつ、 ``dynamic`` にも挙げて" -"ある場合には、ビルド用バックエンドはエラーを発生させなければなりません。" -#: ../source/specifications/pyproject-toml.rst:411 +#: ../source/specifications/pyproject-toml.rst:44 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)." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -"メタデータ内で、あるキーを ``dynamic`` の中に挙げなかった場合は、ビルド用バッ" -"クエンドがユーザに代わって必要なメタデータを挿入することはできません (すなわ" -"ち、ツールがメタデータを挿入できるのは ``dynamic`` の中だけであり、かつ、ユー" -"ザがそうするようにオプトインしていなければならないということです) 。" -#: ../source/specifications/pyproject-toml.rst:415 +#: ../source/specifications/pyproject-toml.rst:53 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)." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -"あるキーが ``dynamic`` の中で指定されたメタデータで、しかし、ビルド用バックエ" -"ンドがそこに挿入するべきデータを決定することができない時は、ビルド用バックエ" -"ンドはエラーを発生させなければなりません (正確な値であると判断した場合はデー" -"タを省略することが許容されます) 。" -#: ../source/specifications/pyproject-toml.rst:425 -msgid "Arbitrary tool configuration: the ``[tool]`` table" +#: ../source/specifications/pyproject-toml.rst:56 +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/pyproject-toml.rst:427 +#: ../source/specifications/pyproject-toml.rst:65 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]``." +"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/pyproject-toml.rst:433 +#: ../source/specifications/pyproject-toml.rst:103 +#, fuzzy +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "プロジェクトのメタデータを宣言する" + +#: ../source/specifications/pyproject-toml.rst:105 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." +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/pyproject-toml.rst:444 +#: ../source/specifications/pyproject-toml.rst:107 msgid "" -"May 2016: The initial specification of the ``pyproject.toml`` file, with " -"just a ``[build-system]`` containing a ``requires`` key and a ``[tool]`` " -"table, was approved through :pep:`518`." +"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/pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:115 msgid "" -"November 2020: The specification of the ``[project]`` table was approved " -"through :pep:`621`." +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:7 -msgid "Recording installed projects" -msgstr "インストール済みのプロジェクトを記録する" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" +msgstr "必ず静的に定義しなければならない必須のキーは次の通り:" -#: ../source/specifications/recording-installed-packages.rst:9 +#: ../source/specifications/pyproject-toml.rst:122 msgid "" -"This document specifies a common format of recording information about " -"Python :term:`projects ` installed in an environment. A common " -"metadata format allows tools to query, manage or uninstall projects, " -"regardless of how they were installed." +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -"この説明文書では、ある環境にインストールされた Python :term:`プロジェクト " -"` に関する情報を記録するための共通フォーマットについて指定します。共" -"通メタデータフォーマットがあれば、プロジェクトがどのようにインストールされた" -"かに関わりなく、ツールがプロジェクトについて問い合わせを行い、管理し、あるい" -"はアンインストールすることが可能になります。" +"必須フィールドだが、静的に指定しても動的に指定しても *いずれでも構わない* " +"キーは以下の通り:" -#: ../source/specifications/recording-installed-packages.rst:14 +#: ../source/specifications/pyproject-toml.rst:127 msgid "" -"Almost all information is optional. This allows tools outside the Python " -"ecosystem, such as Linux package managers, to integrate with Python tooling " -"as much as possible. For example, even if an installer cannot easily provide " -"a list of installed files in a format specific to Python tooling, it should " -"still record the name and version of the installed project." +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -"ほとんど全ての情報が必須ではないものです。これによって、Linux のパッケージ管" -"理機構のような Python のエコシステムの外にあるツールを Python のツールの使い" -"方と最大限に統合することができます。例えば、ある Python ツールに特化した" -"フォーマットで書かれたインストール済みファイルのリストをインストーラがすぐに" -"は提供できない場合でさえも、インストール済みのプロジェクトの名前とバージョン" -"を記録するべきです。" +"他の全てのキーは必須ではないものと解釈され、これらは静的に指定しても動的にリ" +"ストしても未指定のままにしていても構いません。" -#: ../source/specifications/recording-installed-packages.rst:25 -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 "" -"配布物からインストールされた各プロジェクトは、一連のファイルの他に、インポー" -"ト可能なモジュールやパッケージの隣に位置する \"``.dist-info``\" ディレクトリ" -"もインストールします (通常は ``site-packages`` ディレクトリ) 。" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "``[project]`` テーブルで許容されるキーの完全なリストは次のとおりです:" -#: ../source/specifications/recording-installed-packages.rst:29 -#, 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 the :ref:`name normalization specification ` and the :ref:`version normalization specification `), 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." -msgstr "" -"このディレクトリは ``{name}-{version}.dist-info`` という名前で、 ``name`` と " -"``version`` のフィールドが :ref:`core-metadata` に対応しています。両方の" -"フィールドは正規化 (各フィールドにおける正規化の定義については、それぞれ :" -"ref:`名前の正規化 ` " -"を見てください) されていなければならず、かつ、ダッシュ (``-``) の文字をアン" -"ダースコア (``_``) で置き換えることで ``.dist-info`` ディレクトリが常に正確に" -"ひとつだけのダッシュ (``-``) 文字をそのファイル名基幹部に持ち、それによって " -"``name`` と ``version`` フィールドを分割していなければなりません。" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" +msgstr "``著者 ``" -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" +msgstr "``依存関係 ``" + +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" +msgstr "``保守者 ``" + +#: ../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 "" -"Historically, tools have failed to replace dot characters or normalize case " -"in the ``name`` field, or not perform normalization in the ``version`` " -"field. Tools consuming ``.dist-info`` directories should expect those fields " -"to be unnormalized, and treat them as equivalent to their normalized " -"counterparts. New tools that write ``.dist-info`` directories MUST normalize " -"both ``name`` and ``version`` fields using the rules described above, and " -"existing tools are encouraged to start normalizing those fields." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -"歴史的には、ツール類はドット文字の置換や ``name`` フィールドにおける大文字小" -"文字の正規化に失敗すしたり、 ``version`` フィールドの正規化をしなかったり、と" -"いうことを繰り返してきました。 ``.dist-info`` ディレクトリを利用する側のツー" -"ルは、そのようなフィールドが正規化されていることを期待するべきではなく、それ" -"らを対応する正規化済みのものと同じものだと考えて取り扱うべきです。 ``.dist-" -"info`` ディレクトリに書き込むツールをこれから作るなら、そのツールは ``name`` " -"と ``version`` の両方のフィールドを上記の規則に従って正規化しなければならず、" -"既存のツールもこれらのフィールドの正規化を始めることが推奨されています。" +":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`名前 " +"` フィールド" -#: ../source/specifications/recording-installed-packages.rst:47 +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." +msgstr "プロジェクトの名前。" + +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"The ``.dist-info`` directory's name is formatted to unambiguously 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 distribution information." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -"``.dist-info`` ディレクトリの名前は、曖昧さのない形で配布物をファイルシステム" -"上のパスとして表現するためにフォーマットされています。配布物の名前をユーザに" -"提示するツールは、正規化された名前を使うのを避け、 (インストール済みパッケー" -"ジへの名前解決より前に必要な場合には) 代わりに指定された名前を提示するか、ま" -"たは、コアとなるメタデータの適切なフィールドの値はエスケープ処理もされておら" -"ず配布物を正確に反映しているのでそこから読み取った名前を提示するべきです。ラ" -"イブラリは、配布物の情報を表示する時にツールが正規化されていない名前にアクセ" -"スできるように、そのようなツール群が利用できるような API を提供するべきです。" +"内部的な一貫性を保つために、ツール側では読み取ったらすぐに、この名前を :ref:`" +"正規化 ` するべきです。" -#: ../source/specifications/recording-installed-packages.rst:56 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"This ``.dist-info`` directory may contain the following files, described in " -"detail below:" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -"この ``.dist-info`` ディレクトリには、以下に詳細を述べるこれらのファイルを置" -"くことができます:" +":ref:`コアとなるメタデータ ` に対応する: :ref:`バージョン " +"`" -#: ../source/specifications/recording-installed-packages.rst:59 -msgid "``METADATA``: contains project metadata" -msgstr "``METADATA``: プロジェクトのメタデータを含みます" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" -#: ../source/specifications/recording-installed-packages.rst:60 -msgid "``RECORD``: records the list of installed files." -msgstr "``RECORD``: インストールされるファイルを列挙して記録します。" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "ユーザは正規化済みのバージョンを指定するようにするべきです。" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/pyproject-toml.rst:180 msgid "" -"``INSTALLER``: records the name of the tool used to install the project." +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -"``INSTALLER``: プロジェクトをインストールするのに使われるツールの名前を記録し" -"ます。" +":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`要約 " +"`" -#: ../source/specifications/recording-installed-packages.rst:62 -msgid "``entry_points.txt``: see :ref:`entry-points` for details" -msgstr "" -"``entry_points.txt``: 詳細については :ref:`entry-points` を見てください" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." +msgstr "プロジェクトを要約する記述。" -#: ../source/specifications/recording-installed-packages.rst:63 -msgid "``direct_url.json``: see :ref:`direct-url` for details" -msgstr "``direct_url.json``: 詳細については :ref:`direct-url` を見てください" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" +msgstr "TOML_ 型: 文字列またはテーブル" -#: ../source/specifications/recording-installed-packages.rst:65 +#: ../source/specifications/pyproject-toml.rst:190 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." +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -"``METADATA`` ファイルは必須です。これ以外の全てのファイルは、インストールツー" -"ルの最良で省略可能です。インストーラ独自のファイルが他に存在しても構いませ" -"ん。" +"対応する `コアとなるメタデータ ` フィールド: :ref:" +"`Description ` and :ref:`Description-Content-Type " +"`" -#: ../source/specifications/recording-installed-packages.rst:71 +#: ../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 :ref:`binary-distribution-format` specification describes additional " -"files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " -"Such files may be copied to the ``.dist-info`` directory of an installed " -"project." +"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 "" -":ref:`binary-distribution-format` 仕様では、 :term:`Wheel` の ``.dist-info`` " -"ディレクトリに出現するかもしれない追加のファイルについて記述しています。その" -"ようなファイルをインストールされたプロジェクトの ``.dist-info`` ディレクトリ" -"にコピーしても構いません。" +"このキーは文字列かテーブルを受け付けます。もし文字列なら、完全な説明を含むテ" +"キストファイルの位置を ``pyproject.toml`` からの相対パスで示したものです。" +"ツールの側ではこのファイルが UTF-8 でエンコードされているものと想定しなければ" +"なりません。ファイルパスが大文字小文字を問わず ``.md`` 拡張子で終わっている場" +"合は、ツールはそのファイルの content-type が ``text/markdown`` であるものと仮" +"定しなければなりません。ファイルパスが大文字小文字を問わず ``.rst`` で終わっ" +"ている場合は、ツールは content-type が ``text/x-rst`` であるものと仮定しなけ" +"ればなりません。この PEP で指定するよりも多くの拡張子をツールが認識するなら、" +"そのようなツールは、このキーを ``dynamic`` であると指定していなくても、ユーザ" +"のために content-type を推測しても構いません。content-type が与えられていない" +"場合には、全ての認識できない拡張子についてツールはエラーを発生させなければな" +"りません。" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/pyproject-toml.rst:207 msgid "" -"The previous versions of this specification also specified a ``REQUESTED`` " -"file. This file is now considered a tool-specific extension, but may be " -"standardized again in the future. See `PEP 376 `_ for its original meaning." +"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 "" -"この仕様の以前のバージョンでは、 ``REQUESTED`` ファイルも指定していました。こ" -"のファイルは、現在ではツール特有の拡張であると見做されていますが、いつか再び" -"標準化されるかもしれません。その元々の意味するところについては、 `PEP 376 " -"`_ を見てください。" - -#: ../source/specifications/recording-installed-packages.rst:83 -msgid "The METADATA file" -msgstr "METADATA ファイル" +"``readme`` キーはその値がテーブルでも構いません。 ``file`` キーは、完全な説明" +"を含むファイルへの ``pyproject.toml`` ファイルからの相対パスを表現する文字列" +"を値として持ちます。 ``text`` キーは、完全な説明そのものである文字列を値に持" +"ちます。これらのキーは排他的にいずれかひとつしか使えないので、もしメタデータ" +"がこれら両方のキーを同時に指定していたらツールはエラーを発生させなければなり" +"ません。" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/pyproject-toml.rst:214 msgid "" -"The ``METADATA`` file contains metadata as described in the :ref:`core-" -"metadata` specification, version 1.1 or greater." +"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 "" -"``METADATA`` ファイルには、 :ref:`コアとなるメタデータ ` 仕様" -"のバージョン 1.1 またはそれ以降で記述されているようなメタデータを含みます。" +"``readme`` キーに指定されたテーブルには、完全な説明の content-type を指定する" +"文字列を値とする ``content-type`` キーも含まれています。メタデータがこのキー" +"をテーブルの中で指定していない場合には、ツールはエラーを発生させなければなり" +"ません。メタデータで ``charset`` パラメータが指定されていない場合には、 " +"UTF-8 であるものと想定されます。ツールは各ツールが独自に選択した他のエンコー" +"ディングをサポートしても構いません。 :ref:`コアとなるメタデータ ` によってサポートされている content-type に変換することができるので" +"あれば、ツールはそのような代替 content-type をサポートしても構いません。そう" +"でなければ、ツールはサポートしていない content-type に対してエラーを発生させ" +"なければなりません。" -#: ../source/specifications/recording-installed-packages.rst:88 +#: ../source/specifications/pyproject-toml.rst:229 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." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -"``METADATA`` ファイルは必須のものです。このファイルを作成することができない場" -"合や、必須のコアとなるメタデータが入手できない場合には、インストーラはエラー" -"を発生させてプロジェクトのインストールを失敗させなければなりません。" +":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:" +"`Requires-Python `" -#: ../source/specifications/recording-installed-packages.rst:94 -msgid "The RECORD file" -msgstr "RECORD ファイル" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." +msgstr "プロジェクトが要求する Python のバージョン。" -#: ../source/specifications/recording-installed-packages.rst:96 +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" +msgstr "TOML_ 型: テーブル" + +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"The ``RECORD`` file holds the list of installed files. It is a CSV file " -"containing one record (line) per installed file." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -"``RECORD`` ファイルには、インストールされたファイル群を列挙します。CSV ファイ" -"ルで、インストールされたファイルを１行に一つずつ書き込みます。" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`License `" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"The CSV dialect must be readable with the default ``reader`` of Python's " -"``csv`` module:" +"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 "" -"CSV の亜種としては、 Python の ``csv`` モジュールの ``reader`` で読めるもので" -"なければなりません:" - -#: ../source/specifications/recording-installed-packages.rst:102 -msgid "field delimiter: ``,`` (comma)," -msgstr "フィールド区切り文字: ``,`` (コンマ)、" +"テーブルには二つのキーのうちのいずれか一つを書くことができます。 ``file`` " +"キーは、 ``pyproject.toml`` からプロジェクトのライセンス情報を含むファイルへ" +"の相対パスを値とする文字列です。ツールの側では、そのファイルのエンコーディン" +"グが UTF-8 であるものと仮定しなければなりません。 ``text`` キーは、プロジェク" +"トのライセンス条項そのものである文字列を値に取ります。これらのキーは相互に排" +"他的で、従って、両方のキーが指定されているメタデータについてツールの側ではエ" +"ラーを発生させなければなりません。" -#: ../source/specifications/recording-installed-packages.rst:103 -msgid "quoting char: ``\"`` (straight double quote)," -msgstr "引用符: ``\"`` (ストレートダブルクォート)、" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "TOML_ 型: 文字列のキー・バリュー組を伴ったインラインテーブルの配列" -#: ../source/specifications/recording-installed-packages.rst:104 -msgid "line terminator: either ``\\r\\n`` or ``\\n``." -msgstr "行末文字: ``\\r\\n`` か ``\\n`` のいずれか一方。" +#: ../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/recording-installed-packages.rst:106 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"Each record is composed of three elements: the file's **path**, the **hash** " -"of the contents, and its **size**." +"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/recording-installed-packages.rst:109 +#: ../source/specifications/pyproject-toml.rst:265 msgid "" -"The *path* may be either absolute, or relative to the directory containing " -"the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " -"Windows, directories may be separated either by forward- or backslashes (``/" -"`` or ``\\``)." +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -"*パス* は ``.dist-info`` ディレクトリを含むディレクトリ (通常は ``site-" -"packages`` ディレクトリ) へのパスで、絶対パスでも相対パスでも構いません。 " -"Windows では、ディレクトリはスラッシュで区切ってもバックスラッシュで区切って" -"も構いません (``/`` または ``\\``) 。" +"\"maintainers\" キーは \"authors\" キーに似ていて、その正確な意味はさまざまに" +"解釈可能です。" -#: ../source/specifications/recording-installed-packages.rst:114 -#, fuzzy +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"The *hash* is either an empty string or the name of a hash algorithm from :" -"py:data:`hashlib.algorithms_guaranteed`, followed by the equals character " -"``=`` and the digest of the file's contents, encoded with the urlsafe-base64-" -"nopad encoding (:py:func:`base64.urlsafe_b64encode(digest) ` with trailing ``=`` removed)." +"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 "" -"*hash* は、空文字列または ``hashlib.algorithms_guaranteed`` から取ったハッ" -"シュアルゴリズムの名前の後ろに等号 ``=`` を付けて、ファイルの内容のハッシュ値" -"を urlsafe-base64-nopad エンコーディング (``base64." -"urlsafe_b64encode(digest)`` の結果から末尾の ``=`` を取り除いたもの) で記した" -"ものです。" +"これらのキーは、 ``name`` と ``email`` のふたつのキーを伴ったテーブルの配列を" +"受け入れます。両方の値は文字列でなければなりません。 ``name`` の値は、電子" +"メールアドレスにおける正当な名前 (すなわち、 :rfc:`822` における電子メールア" +"ドレスのアドレス部分に前置できる名前なら何でも可) で、コンマを含まないもので" +"なければなりません。 ``email`` の値は、正当な電子メールアドレスでなければなり" +"ません。これらのキーは共に必須ではありませんが、少なくともいずれかのキーが" +"テーブル内で指定されていなければなりません。" -#: ../source/specifications/recording-installed-packages.rst:119 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"The *size* is either the empty string, or file's size in bytes, as a base 10 " -"integer." +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -"*size* は、空文字列か、または、ファイルサイズを 10 進数のバイト数で書いたもの" -"です。" +"データを使って :ref:`コアとなるメタデータ ` に書き込むやり方は" +"次の通りです:" -#: ../source/specifications/recording-installed-packages.rst:122 +#: ../source/specifications/pyproject-toml.rst:278 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 " -"have empty *hash* and *size*. For other files, leaving the information out " -"is discouraged, as it prevents verifying the integrity of the installed " -"project." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -"どのファイルについても、 *hash* フィールドと *size* フィールドの片方もしくは" -"両方が空欄になっていても構いません。通常は、 ``.pyc`` ファイルと ``RECORDS`` " -"ファイル自身については *hash* フィールドと *size* フィールドの両方が空欄に" -"なっています。その他のファイルについては、インストールされたプロジェクトに関" -"する完全性を検証するために情報を与えておくことが推奨されています。" +"``name`` だけが与えられた場合には、その値を :ref:`Author ` なり :ref:`Maintainer ` なりに書き込みま" +"す。" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/pyproject-toml.rst:281 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 " -"``RECORD``, which are optional. Notably, the contents of the ``.dist-info`` " -"directory (including the ``RECORD`` file itself) must be listed. Directories " -"should not be listed." +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -"もし ``RECORD`` ファイルが存在するなら、 ``RECORD`` に記入された ``.py`` ファ" -"イルに対応する ``.pyc`` ファイルを記入することはオプションですが、それを除い" -"てそのプロジェクトからインストールされたファイルの全てについて列挙していなけ" -"ればなりません。特に、 ``.dist-info`` ディレクトリ の内容 (``RECORD`` ファイ" -"ル自身を含む) については、書いておかなければなりません。ディレクトリについて" -"は記入してはなりません。" +"``email`` だけの場合には、その値を :ref:`Author-email ` なり :ref:`Maintainer-email ` なりに" +"書き込みます。" -#: ../source/specifications/recording-installed-packages.rst:135 +#: ../source/specifications/pyproject-toml.rst:285 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." +"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 "" -"パッケージを完全にアンインストールするためには、ツールは、 ``RECORD`` に列挙" -"された全てのファイルと、 ``.py`` ファイルに対応する (あらゆる最適化状態の) " -"``.pyc`` ファイルと、アンインストールによって空になったすべてのディレクトリを" -"削除する必要があります。" +"``email`` と ``name`` の両方が与えられた場合には、 ``{name} <{email}>`` の" +"フォーマットで :ref:`Author-email ` なり :ref:" +"`Maintainer-email ` なりに書き込みます。" -#: ../source/specifications/recording-installed-packages.rst:140 -msgid "Here is an example snippet of a possible ``RECORD`` file::" -msgstr "ありうる ``RECORD`` ファイルの一部を切り出した例をここに掲げます::" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." +msgstr "複数の値がある場合はコンマで区切るべきです。" -#: ../source/specifications/recording-installed-packages.rst:159 +#: ../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 "" -"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 " -"apply to tools that rely on other sources of information, such as system " -"package managers in Linux distros.)" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -"``RECORD`` ファイルが存在しない場合、 ``.dist-info`` に依存するツールは、アン" -"インストールやアップグレードを試みてはなりません。(この制約は、 Linux ディス" -"トロにおけるシステムのパッケージ管理機構のような、それ以外の情報源に依存する" -"ツールには適用されません。)" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`Keywords ` field: :ref:`Classifier " +"`" msgstr "" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`Classifier `" -#: ../source/specifications/recording-installed-packages.rst:175 -msgid "The INSTALLER file" -msgstr "INSTALLER ファイル" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." +msgstr "プロジェクトに適合する Trove 分類子。" -#: ../source/specifications/recording-installed-packages.rst:177 +#: ../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 "" -"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, " -"``INSTALLER`` should contain the command name. Otherwise, it should contain " -"a printable ASCII string." +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -"もし存在するなら、 ``INSTALLER`` は、プロジェクトのインストールに使われたツー" -"ルを名指しする１行のテキストファイルです。インストーラがコマンドラインから起" -"動されるなら、 ``INSTALLER`` はそのコマンドの名前を含んでいるべきです。そうで" -"なければ印刷可能な ASCII 文字を含んでいるべきです。" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`Project-URL `" -#: ../source/specifications/recording-installed-packages.rst:183 -msgid "The file can be terminated by zero or more ASCII whitespace characters." +#: ../source/specifications/pyproject-toml.rst:319 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -"ファイルは、0個またはそれ以上の ASCII 空白文字で終端することができます。" +"URL のテーブルで、 URL に付けられたラベルがキーで URL そのものが値になってい" +"るもの。" -#: ../source/specifications/recording-installed-packages.rst:185 -msgid "Here are examples of two possible ``INSTALLER`` files::" -msgstr "``INSTALLER`` ファイルについて、二つの可能な例を示します::" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" +msgstr "エントリポイント" -#: ../source/specifications/recording-installed-packages.rst:193 +#: ../source/specifications/pyproject-toml.rst:326 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 " -"suggest that the tool named in ``INSTALLER`` may be able to do the " -"uninstallation." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -"この値は情報提供目的にのみ使用されるべきです。例えば、あるツールでプロジェク" -"トのアンインストールをしようとしたが ``RECORD`` ファイルを見つけられなかった" -"場合には、そのツールは ``INSTALLER`` ファイルに書いてある (別の) ツールを使え" -"ばアンインストールができるかもしれないと示唆しても構いません。" +"TOML_ 型: table (``[project.scripts]`` ・ ``[project.gui-scripts]`` ・ " +"``[project.entry-points]``)" -#: ../source/specifications/recording-installed-packages.rst:200 -msgid "The entry_points.txt file" -msgstr "entry_points.txt ファイル" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr ":ref:`Entry points specification `" -#: ../source/specifications/recording-installed-packages.rst:202 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"This file MAY be created by installers to indicate when packages contain " -"components intended for discovery and use by other code, including console " -"scripts and other applications that the installer has made available for " -"execution." +"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/recording-installed-packages.rst:207 -msgid "Its detailed specification is at :ref:`entry-points`." -msgstr "その詳細な仕様は :ref:`entry-points` にあります。" - -#: ../source/specifications/recording-installed-packages.rst:211 -msgid "The direct_url.json file" -msgstr "direct_url.json ファイル" +"みっつのテーブルがエントリポイントに関係しています。 ``[project.scripts]`` " +"テーブルは、 :ref:`エントリポイント仕様 ` の中の " +"``console_scripts`` グループに対応しています。テーブル内のキーはエントリポイ" +"ントの名前であり、値は参照されるオブジェクトです。" -#: ../source/specifications/recording-installed-packages.rst:213 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"This file MUST be created by installers when installing a distribution from " -"a requirement specifying a direct URL reference (including a VCS URL)." +"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 (VCS の URL を含む) から配布" -"物をインストールする際に、インストーラによって生成されなければなりません。" - -#: ../source/specifications/recording-installed-packages.rst:219 -msgid "Its detailed specification is at :ref:`direct-url`." -msgstr "その詳細な仕様は :ref:`direct-url` にあります。" +"``[project.gui-scripts]`` テーブルは、 :ref:`エントリポイント仕様 ` の中の ``gui_scripts`` グループに対応します。そのフォーマットは " +"``[project.scripts]`` と同じです。" -#: ../source/specifications/recording-installed-packages.rst:223 -msgid "Intentionally preventing changes to installed packages" -msgstr "インストール済みのパッケージ群への変更を意図的に防ぐ" +#: ../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 "" +"``[project.entry-points]`` テーブルは、テーブルの集合体です。それぞれのサブ" +"テーブルの名前は、ひとつのエントリポイントグループです。キーと値の意味すると" +"ころは ``[project.scripts]`` と同じです。ユーザはネストしたサブテーブルを作っ" +"てはならず、代わりにエントリポイントグループを１段階の深さに保つようにしなけ" +"ればなりません。" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/pyproject-toml.rst:346 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 " -"installs packages into a Python environment to ensure that other tools are " -"not used to uninstall or otherwise modify that installed package, as doing " -"so may cause compatibility problems with the wider environment." +"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 エコシステムでの依存関係に加えて外部の依存関係を管理する必要がある場" -"合など) いくつかの場合には、 Python 環境にパッケージをインストールするツール" -"が、そのインストール済みパッケージを他のツールがアンインストールも修正もして" -"いないことを、もしそんなことをしていればより広範な環境に互換性問題を引き起こ" -"しかねないので、しっかりと確認することが望ましいです。" +"メタデータの中に ``[project.entry-points.console_scripts]`` もしくは " +"``[project.entry-points.gui_scripts]`` というテーブルが定義されている場合は、" +"それぞれ ``[project.scripts]`` や ``[project.gui-scripts]`` と混同してしまう" +"といけないので、ビルド時のバックエンドがエラーを発生させなければなりません。" -#: ../source/specifications/recording-installed-packages.rst:231 -msgid "To achieve this, affected tools should take the following steps:" +#: ../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/recording-installed-packages.rst:233 +#: ../source/specifications/pyproject-toml.rst:359 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 " -"tool itself needs the information, or omitting the file entirely if the " -"package contents are tracked and managed via other means)" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -"他のツール類を経由した変更を抑止するために、``RECORD`` ファイルを別の名前にす" -"るか、削除するか (このファイル内の情報が必要なら、例えば標準的でない名前の " -"``RECORD.tool`` というファイルを作成するために拡張子を追加すること、あるい" -"は、パッケージの内容物を他の手段で追跡・管理しているのであればファイルを完全" -"に除外しておくこと) してください。" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`Requires-Dist ` および :ref:`Provides-Extra " +"`" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." +msgstr "(必須ではない) プロジェクトの依存関係。" + +#: ../source/specifications/pyproject-toml.rst:365 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)" +"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 "" -"そのパッケージを管理するのに使用されるべきツールの名前を示すように" -"``INSTALLER`` ファイルを書いてください (これによって、 ``RECORD`` を参照でき" -"るツール群が影響を被るパッケージを修正するように言われた時により良いエラー通" -"知を提供できます)" +"``dependencies`` には、文字列の配列が値であるようなキーです。それぞれの文字列" +"がそのプロジェクトの依存関係を表現していて、正当な :pep:`508` の文字列として" +"フォーマットされていなければなりません。それぞれの文字列は、 :ref:`Requires-" +"Dist ` エントリに直接にマップしています。" -#: ../source/specifications/recording-installed-packages.rst:241 +#: ../source/specifications/pyproject-toml.rst:370 msgid "" -"Python runtime providers may also prevent inadvertent modification of " -"platform provided packages by modifying the default Python package " -"installation scheme to use a location other than that used by platform " -"provided packages (while also ensuring both locations appear on the default " -"Python import path)." +"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 "" -"Python ランタイムの提供者は、デフォルトの Python パッケージのインストレーショ" -"ンスキームを修正してプラットフォームが提供するパッケージ群で使われるものとは" -"別の場所を使うようにすることで、プラットフォームが提供するパッケージ群を意図" -"せずに修正してしまうことを防いでも構いません。" +"``optional-dependencies`` は、それぞれのキーが追加物で、その値が文字列の配列" +"であるようなテーブルです。文字列の配列は正当な :pep:`508` の文字列でなければ" +"なりません。キーは :ref:`Provides-Extra ` とし" +"てみた時に正当な値でなければなりません。従って、配列の中のそれぞれの値は、一" +"致する :ref:`Provides-Extra ` メタデータに対応" +"する :ref:`Requires-Dist ` のエントリになりま" +"す。" -#: ../source/specifications/recording-installed-packages.rst:246 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" +msgstr "TOML_ 型: 文字列の配列" + +#: ../source/specifications/pyproject-toml.rst:387 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:" -"`externally-managed-environments`" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -"いくつかの環境では、 Python 特有のツール群を経由した追加パッケージのインス" -"トールさえもブロックすることが望ましいかもしれません。このようなケースについ" -"ては :ref:`外部から管理される環境 ` を参照し" -"てください" +":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`ダイ" +"ナミック ` フィールド" -#: ../source/specifications/recording-installed-packages.rst:254 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"June 2009: The original version of this specification was approved through :" -"pep:`376`. At the time, it was known as the *Database of Installed Python " -"Distributions*." +"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/recording-installed-packages.rst:257 +#: ../source/specifications/pyproject-toml.rst:396 msgid "" -"March 2020: The specification of the ``direct_url.json`` file was approved " -"through :pep:`610`. It is only mentioned on this page; see :ref:`direct-url` " -"for the full definition." +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" +"ビルド用のバックエンドは、静的に指定されたメタデータ (つまり ``dynamic`` 内に" +"列挙されたキーではないメタデータ) を尊重しなければなりません。" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"September 2020: Various amendments and clarifications were approved through :" -"pep:`627`." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" +"メタデータで ``dynamic`` 内に ``name`` が指定されている場合には、ビルド用バッ" +"クエンドがエラーを発生させなければなりません。" -#: ../source/specifications/section-distribution-formats.rst:3 -msgid "Package Distribution File Formats" -msgstr "パッケージ配布物のファイルフォーマット" - -#: ../source/specifications/section-distribution-metadata.rst:3 -msgid "Package Distribution Metadata" -msgstr "パッケージ配布物のメタデータ" - -#: ../source/specifications/section-installation-metadata.rst:3 -#, fuzzy -msgid "Package Installation Metadata" -msgstr "パッケージのインストール環境のメタデータ" - -#: ../source/specifications/section-package-indices.rst:3 -msgid "Package Index Interfaces" -msgstr "パッケージインデックスのインタフェース" - -#: ../source/specifications/simple-repository-api.rst:6 -msgid "Simple repository API" -msgstr "シンプルなリポジトリ API" - -#: ../source/specifications/simple-repository-api.rst:8 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"The interface for querying available package versions and retrieving " -"packages from an index server comes in two forms: HTML and JSON." +"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 "" -"利用可能なパッケージバージョンを問い合わせたり、インデックスサーバからパッ" -"ケージを取り出したりするためのインターフェースは、二つの形式: HTML と JSON で" -"もたらされます。" +":ref:`コアとなるメタデータ ` の仕様において、あるキーが \"必須" +"である\" ものとして挙げられている場合には、メタデータはそのキーを静的に指定す" +"るか、または、 ``dynamic`` 内に指定するかしなければなりません (どちらでもない" +"場合にはビルドバックエンドがエラーを発生させなければなりません、すなわち、必" +"須のフィールドが ``[project]`` テーブルの中にどんな形でも存在していないという" +"ことは不可能であるべきです)。" -#: ../source/specifications/simple-repository-api.rst:15 -msgid "Base HTML API" +#: ../source/specifications/pyproject-toml.rst:405 +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." msgstr "" +":ref:`コアとなるメタデータ ` の仕様で、あるキーを \"必須ではな" +"い\" ものとして挙げている場合には、後でビルド用バックエンドがそのキー用のデー" +"タを提供するという期待が持てるのであればメタデータではそのキーを ``dynamic`` " +"の中に挙げても構いません。" -#: ../source/specifications/simple-repository-api.rst:17 +#: ../source/specifications/pyproject-toml.rst:409 msgid "" -"A repository that implements the simple API is defined by its base URL, this " -"is the top level URL that all additional URLs are below. The API is named " -"the \"simple\" repository due to the fact that PyPI's base URL is ``https://" -"pypi.org/simple/``." +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" +"メタデータ内で、あるキーが静的に指定されていて、かつ、 ``dynamic`` にも挙げて" +"ある場合には、ビルド用バックエンドはエラーを発生させなければなりません。" -#: ../source/specifications/simple-repository-api.rst:22 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"All subsequent URLs in this document will be relative to this base URL (so " -"given PyPI's URL, a URL of ``/foo/`` would be ``https://pypi.org/simple/foo/" -"``." +"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 "" +"メタデータ内で、あるキーを ``dynamic`` の中に挙げなかった場合は、ビルド用バッ" +"クエンドがユーザに代わって必要なメタデータを挿入することはできません (すなわ" +"ち、ツールがメタデータを挿入できるのは ``dynamic`` の中だけであり、かつ、ユー" +"ザがそうするようにオプトインしていなければならないということです) 。" -#: ../source/specifications/simple-repository-api.rst:27 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"Within a repository, the root URL (``/`` for this spec which represents the " -"base URL) **MUST** be a valid HTML5 page with a single anchor element per " -"project in the repository. The text of the anchor tag **MUST** be the name " -"of the project and the href attribute **MUST** link to the URL for that " -"particular project. As an example::" +"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 "" +"あるキーが ``dynamic`` の中で指定されたメタデータで、しかし、ビルド用バックエ" +"ンドがそこに挿入するべきデータを決定することができない時は、ビルド用バックエ" +"ンドはエラーを発生させなければなりません (正確な値であると判断した場合はデー" +"タを省略することが許容されます) 。" + +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/simple-repository-api.rst:41 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"Below the root URL is another URL for each individual project contained " -"within a repository. The format of this URL is ``//`` where the " -"```` is replaced by the normalized name for that project, so a " -"project named \"HolyGrail\" would have a URL like ``/holygrail/``. This URL " -"must respond with a valid HTML5 page with a single anchor element per file " -"for the project. The href attribute **MUST** be a URL that links to the " -"location of the file for download, and the text of the anchor tag **MUST** " -"match the final path component (the filename) of the URL. The URL **SHOULD** " -"include a hash in the form of a URL fragment with the following syntax: " -"``#=``, where ```` is the lowercase name of " -"the hash function (such as ``sha256``) and ```` is the hex " -"encoded digest." +"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/simple-repository-api.rst:53 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"In addition to the above, the following constraints are placed on the API:" +"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/simple-repository-api.rst:55 +#: ../source/specifications/pyproject-toml.rst:444 msgid "" -"All URLs which respond with an HTML5 page **MUST** end with a ``/`` and the " -"repository **SHOULD** redirect the URLs without a ``/`` to add a ``/`` to " -"the end." +"May 2016: The initial specification of the ``pyproject.toml`` file, with " +"just a ``[build-system]`` containing a ``requires`` key and a ``[tool]`` " +"table, was approved through :pep:`518`." msgstr "" -#: ../source/specifications/simple-repository-api.rst:59 +#: ../source/specifications/pyproject-toml.rst:448 msgid "" -"URLs may be either absolute or relative as long as they point to the correct " -"location." +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." msgstr "" -#: ../source/specifications/simple-repository-api.rst:62 +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "インストール済みのプロジェクトを記録する" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" -"There are no constraints on where the files must be hosted relative to the " -"repository." +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." msgstr "" +"この説明文書では、ある環境にインストールされた Python :term:`プロジェクト " +"` に関する情報を記録するための共通フォーマットについて指定します。共" +"通メタデータフォーマットがあれば、プロジェクトがどのようにインストールされた" +"かに関わりなく、ツールがプロジェクトについて問い合わせを行い、管理し、あるい" +"はアンインストールすることが可能になります。" -#: ../source/specifications/simple-repository-api.rst:65 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" -"There may be any other HTML elements on the API pages as long as the " -"required anchor elements exist." +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"as much as possible. For example, even if an installer cannot easily provide " +"a list of installed files in a format specific to Python tooling, it should " +"still record the name and version of the installed project." msgstr "" +"ほとんど全ての情報が必須ではないものです。これによって、Linux のパッケージ管" +"理機構のような Python のエコシステムの外にあるツールを Python のツールの使い" +"方と最大限に統合することができます。例えば、ある Python ツールに特化した" +"フォーマットで書かれたインストール済みファイルのリストをインストーラがすぐに" +"は提供できない場合でさえも、インストール済みのプロジェクトの名前とバージョン" +"を記録するべきです。" -#: ../source/specifications/simple-repository-api.rst:68 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" -"Repositories **MAY** redirect unnormalized URLs to the canonical normalized " -"URL (e.g. ``/Foobar/`` may redirect to ``/foobar/``), however clients **MUST " -"NOT** rely on this redirection and **MUST** request the normalized URL." +"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 "" +"配布物からインストールされた各プロジェクトは、一連のファイルの他に、インポー" +"ト可能なモジュールやパッケージの隣に位置する \"``.dist-info``\" ディレクトリ" +"もインストールします (通常は ``site-packages`` ディレクトリ) 。" -#: ../source/specifications/simple-repository-api.rst:73 +#: ../source/specifications/recording-installed-packages.rst:29 +#, fuzzy msgid "" -"Repositories **SHOULD** choose a hash function from one of the ones " -"guaranteed to be available via the :py:mod:`hashlib` module in the Python " -"standard library (currently ``md5``, ``sha1``, ``sha224``, ``sha256``, " -"``sha384``, ``sha512``). The current recommendation is to use ``sha256``." +"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 the :ref:`name normalization specification ` and the :ref:`version normalization specification `), 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." msgstr "" +"このディレクトリは ``{name}-{version}.dist-info`` という名前で、 ``name`` と " +"``version`` のフィールドが :ref:`core-metadata` に対応しています。両方の" +"フィールドは正規化 (各フィールドにおける正規化の定義については、それぞれ :" +"ref:`名前の正規化 ` " +"を見てください) されていなければならず、かつ、ダッシュ (``-``) の文字をアン" +"ダースコア (``_``) で置き換えることで ``.dist-info`` ディレクトリが常に正確に" +"ひとつだけのダッシュ (``-``) 文字をそのファイル名基幹部に持ち、それによって " +"``name`` と ``version`` フィールドを分割していなければなりません。" -#: ../source/specifications/simple-repository-api.rst:78 +#: ../source/specifications/recording-installed-packages.rst:37 msgid "" -"If there is a GPG signature for a particular distribution file it **MUST** " -"live alongside that file with the same name with a ``.asc`` appended to it. " -"So if the file ``/packages/HolyGrail-1.0.tar.gz`` existed and had an " -"associated signature, the signature would be located at ``/packages/" -"HolyGrail-1.0.tar.gz.asc``." +"Historically, tools have failed to replace dot characters or normalize case " +"in the ``name`` field, or not perform normalization in the ``version`` " +"field. Tools consuming ``.dist-info`` directories should expect those fields " +"to be unnormalized, and treat them as equivalent to their normalized " +"counterparts. New tools that write ``.dist-info`` directories MUST normalize " +"both ``name`` and ``version`` fields using the rules described above, and " +"existing tools are encouraged to start normalizing those fields." msgstr "" +"歴史的には、ツール類はドット文字の置換や ``name`` フィールドにおける大文字小" +"文字の正規化に失敗すしたり、 ``version`` フィールドの正規化をしなかったり、と" +"いうことを繰り返してきました。 ``.dist-info`` ディレクトリを利用する側のツー" +"ルは、そのようなフィールドが正規化されていることを期待するべきではなく、それ" +"らを対応する正規化済みのものと同じものだと考えて取り扱うべきです。 ``.dist-" +"info`` ディレクトリに書き込むツールをこれから作るなら、そのツールは ``name`` " +"と ``version`` の両方のフィールドを上記の規則に従って正規化しなければならず、" +"既存のツールもこれらのフィールドの正規化を始めることが推奨されています。" -#: ../source/specifications/simple-repository-api.rst:84 +#: ../source/specifications/recording-installed-packages.rst:47 msgid "" -"A repository **MAY** include a ``data-gpg-sig`` attribute on a file link " -"with a value of either ``true`` or ``false`` to indicate whether or not " -"there is a GPG signature. Repositories that do this **SHOULD** include it on " -"every link." +"The ``.dist-info`` directory's name is formatted to unambiguously 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 distribution information." msgstr "" +"``.dist-info`` ディレクトリの名前は、曖昧さのない形で配布物をファイルシステム" +"上のパスとして表現するためにフォーマットされています。配布物の名前をユーザに" +"提示するツールは、正規化された名前を使うのを避け、 (インストール済みパッケー" +"ジへの名前解決より前に必要な場合には) 代わりに指定された名前を提示するか、ま" +"たは、コアとなるメタデータの適切なフィールドの値はエスケープ処理もされておら" +"ず配布物を正確に反映しているのでそこから読み取った名前を提示するべきです。ラ" +"イブラリは、配布物の情報を表示する時にツールが正規化されていない名前にアクセ" +"スできるように、そのようなツール群が利用できるような API を提供するべきです。" -#: ../source/specifications/simple-repository-api.rst:88 +#: ../source/specifications/recording-installed-packages.rst:56 msgid "" -"A repository **MAY** include a ``data-requires-python`` attribute on a file " -"link. This exposes the :ref:`core-metadata-requires-python` metadata field " -"for the corresponding release. Where this is present, installer tools " -"**SHOULD** ignore the download when installing to a Python version that " -"doesn't satisfy the requirement. For example::" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" msgstr "" +"この ``.dist-info`` ディレクトリには、以下に詳細を述べるこれらのファイルを置" +"くことができます:" -#: ../source/specifications/simple-repository-api.rst:96 -msgid "" -"In the attribute value, < and > have to be HTML encoded as ``<`` and " -"``>``, respectively." -msgstr "" +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "``METADATA``: プロジェクトのメタデータを含みます" -#: ../source/specifications/simple-repository-api.rst:100 -#, fuzzy -msgid "Normalized Names" -msgstr "正当な非正規化名" +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "``RECORD``: インストールされるファイルを列挙して記録します。" -#: ../source/specifications/simple-repository-api.rst:102 +#: ../source/specifications/recording-installed-packages.rst:61 msgid "" -"This spec references the concept of a \"normalized\" project name. As per :" -"ref:`the name normalization specification ` the only " -"valid characters in a name are the ASCII alphabet, ASCII numbers, ``.``, ``-" -"``, and ``_``. 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::" +"``INSTALLER``: records the name of the tool used to install the project." msgstr "" +"``INSTALLER``: プロジェクトをインストールするのに使われるツールの名前を記録し" +"ます。" -#: ../source/specifications/simple-repository-api.rst:117 -msgid "Adding \"Yank\" Support to the Simple API" +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" +"``entry_points.txt``: 詳細については :ref:`entry-points` を見てください" -#: ../source/specifications/simple-repository-api.rst:119 +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "``direct_url.json``: 詳細については :ref:`direct-url` を見てください" + +#: ../source/specifications/recording-installed-packages.rst:65 msgid "" -"Links in the simple repository **MAY** have a ``data-yanked`` attribute " -"which may have no value, or may have an arbitrary string as a value. The " -"presence of a ``data-yanked`` attribute **SHOULD** be interpreted as " -"indicating that the file pointed to by this particular link has been " -"\"Yanked\", and should not generally be selected by an installer, except " -"under specific scenarios." +"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 "" +"``METADATA`` ファイルは必須です。これ以外の全てのファイルは、インストールツー" +"ルの最良で省略可能です。インストーラ独自のファイルが他に存在しても構いませ" +"ん。" -#: ../source/specifications/simple-repository-api.rst:126 +#: ../source/specifications/recording-installed-packages.rst:71 msgid "" -"The value of the ``data-yanked`` attribute, if present, is an arbitrary " -"string that represents the reason for why the file has been yanked. Tools " -"that process the simple repository API **MAY** surface this string to end " -"users." +"The :ref:`binary-distribution-format` specification describes additional " +"files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " +"Such files may be copied to the ``.dist-info`` directory of an installed " +"project." msgstr "" +":ref:`binary-distribution-format` 仕様では、 :term:`Wheel` の ``.dist-info`` " +"ディレクトリに出現するかもしれない追加のファイルについて記述しています。その" +"ようなファイルをインストールされたプロジェクトの ``.dist-info`` ディレクトリ" +"にコピーしても構いません。" -#: ../source/specifications/simple-repository-api.rst:131 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "" -"The yanked attribute is not immutable once set, and may be rescinded in the " -"future (and once rescinded, may be reset as well). Thus API users **MUST** " -"be able to cope with a yanked file being \"unyanked\" (and even yanked " -"again)." +"The previous versions of this specification also specified a ``REQUESTED`` " +"file. This file is now considered a tool-specific extension, but may be " +"standardized again in the future. See `PEP 376 `_ for its original meaning." msgstr "" +"この仕様の以前のバージョンでは、 ``REQUESTED`` ファイルも指定していました。こ" +"のファイルは、現在ではツール特有の拡張であると見做されていますが、いつか再び" +"標準化されるかもしれません。その元々の意味するところについては、 `PEP 376 " +"`_ を見てください。" -#: ../source/specifications/simple-repository-api.rst:138 -#, fuzzy -msgid "Installers" -msgstr "インストーラ" +#: ../source/specifications/recording-installed-packages.rst:83 +msgid "The METADATA file" +msgstr "METADATA ファイル" -#: ../source/specifications/simple-repository-api.rst:140 +#: ../source/specifications/recording-installed-packages.rst:85 msgid "" -"The desirable experience for users is that once a file is yanked, when a " -"human being is currently trying to directly install a yanked file, that it " -"fails as if that file had been deleted. However, when a human did that " -"awhile ago, and now a computer is just continuing to mechanically follow the " -"original order to install the now yanked file, then it acts as if it had not " -"been yanked." +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." msgstr "" +"``METADATA`` ファイルには、 :ref:`コアとなるメタデータ ` 仕様" +"のバージョン 1.1 またはそれ以降で記述されているようなメタデータを含みます。" -#: ../source/specifications/simple-repository-api.rst:147 +#: ../source/specifications/recording-installed-packages.rst:88 msgid "" -"An installer **MUST** ignore yanked releases, if the selection constraints " -"can be satisfied with a non-yanked version, and **MAY** refuse to use a " -"yanked release even if it means that the request cannot be satisfied at all. " -"An implementation **SHOULD** choose a policy that follows the spirit of the " -"intention above, and that prevents \"new\" dependencies on yanked releases/" -"files." +"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 "" +"``METADATA`` ファイルは必須のものです。このファイルを作成することができない場" +"合や、必須のコアとなるメタデータが入手できない場合には、インストーラはエラー" +"を発生させてプロジェクトのインストールを失敗させなければなりません。" -#: ../source/specifications/simple-repository-api.rst:154 +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "The RECORD file" +msgstr "RECORD ファイル" + +#: ../source/specifications/recording-installed-packages.rst:96 msgid "" -"What this means is left up to the specific installer, to decide how to best " -"fit into the overall usage of their installer. However, there are two " -"suggested approaches to take:" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." msgstr "" +"``RECORD`` ファイルには、インストールされたファイル群を列挙します。CSV ファイ" +"ルで、インストールされたファイルを１行に一つずつ書き込みます。" -#: ../source/specifications/simple-repository-api.rst:158 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "" -"Yanked files are always ignored, unless they are the only file that matches " -"a version specifier that \"pins\" to an exact version using either ``==`` " -"(without any modifiers that make it a range, such as ``.*``) or ``===``. " -"Matching this version specifier should otherwise be done as per :ref:`the " -"version specifiers specification ` for things like local " -"versions, zero padding, etc." +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" msgstr "" +"CSV の亜種としては、 Python の ``csv`` モジュールの ``reader`` で読めるもので" +"なければなりません:" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "field delimiter: ``,`` (comma)," +msgstr "フィールド区切り文字: ``,`` (コンマ)、" + +#: ../source/specifications/recording-installed-packages.rst:103 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "引用符: ``\"`` (ストレートダブルクォート)、" + +#: ../source/specifications/recording-installed-packages.rst:104 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "行末文字: ``\\r\\n`` か ``\\n`` のいずれか一方。" -#: ../source/specifications/simple-repository-api.rst:165 +#: ../source/specifications/recording-installed-packages.rst:106 msgid "" -"Yanked files are always ignored, unless they are the only file that matches " -"what a lock file (such as ``Pipfile.lock`` or ``poetry.lock``) specifies to " -"be installed. In this case, a yanked file **SHOULD** not be used when " -"creating or updating a lock file from some input file or command." +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." msgstr "" +"各レコードは３個の要素から構成されます: ファイルの **パス** 、内容の **ハッ" +"シュ値** 、そして、その **サイズ** です。" -#: ../source/specifications/simple-repository-api.rst:171 +#: ../source/specifications/recording-installed-packages.rst:109 msgid "" -"Regardless of the specific strategy that an installer chooses for deciding " -"when to install yanked files, an installer **SHOULD** emit a warning when it " -"does decide to install a yanked file. That warning **MAY** utilize the value " -"of the ``data-yanked`` attribute (if it has a value) to provide more " -"specific feedback to the user about why that file had been yanked." +"The *path* may be either absolute, or relative to the directory containing " +"the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " +"Windows, directories may be separated either by forward- or backslashes (``/" +"`` or ``\\``)." msgstr "" +"*パス* は ``.dist-info`` ディレクトリを含むディレクトリ (通常は ``site-" +"packages`` ディレクトリ) へのパスで、絶対パスでも相対パスでも構いません。 " +"Windows では、ディレクトリはスラッシュで区切ってもバックスラッシュで区切って" +"も構いません (``/`` または ``\\``) 。" -#: ../source/specifications/simple-repository-api.rst:179 -msgid "Mirrors" +#: ../source/specifications/recording-installed-packages.rst:114 +#, fuzzy +msgid "" +"The *hash* is either an empty string or the name of a hash algorithm from :" +"py:data:`hashlib.algorithms_guaranteed`, followed by the equals character " +"``=`` and the digest of the file's contents, encoded with the urlsafe-base64-" +"nopad encoding (:py:func:`base64.urlsafe_b64encode(digest) ` with trailing ``=`` removed)." msgstr "" +"*hash* は、空文字列または ``hashlib.algorithms_guaranteed`` から取ったハッ" +"シュアルゴリズムの名前の後ろに等号 ``=`` を付けて、ファイルの内容のハッシュ値" +"を urlsafe-base64-nopad エンコーディング (``base64." +"urlsafe_b64encode(digest)`` の結果から末尾の ``=`` を取り除いたもの) で記した" +"ものです。" -#: ../source/specifications/simple-repository-api.rst:181 -msgid "Mirrors can generally treat yanked files one of two ways:" +#: ../source/specifications/recording-installed-packages.rst:119 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." msgstr "" +"*size* は、空文字列か、または、ファイルサイズを 10 進数のバイト数で書いたもの" +"です。" -#: ../source/specifications/simple-repository-api.rst:183 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" -"They may choose to omit them from their simple repository API completely, " -"providing a view over the repository that shows only \"active\", unyanked " -"files." +"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 " +"have empty *hash* and *size*. For other files, leaving the information out " +"is discouraged, as it prevents verifying the integrity of the installed " +"project." msgstr "" +"どのファイルについても、 *hash* フィールドと *size* フィールドの片方もしくは" +"両方が空欄になっていても構いません。通常は、 ``.pyc`` ファイルと ``RECORDS`` " +"ファイル自身については *hash* フィールドと *size* フィールドの両方が空欄に" +"なっています。その他のファイルについては、インストールされたプロジェクトに関" +"する完全性を検証するために情報を与えておくことが推奨されています。" -#: ../source/specifications/simple-repository-api.rst:186 +#: ../source/specifications/recording-installed-packages.rst:128 msgid "" -"They may choose to include yanked files, and additionally mirror the ``data-" -"yanked`` attribute as well." +"If the ``RECORD`` file is present, it must list all installed files of the " +"project, except ``.pyc`` files corresponding to ``.py`` files listed in " +"``RECORD``, which are optional. Notably, the contents of the ``.dist-info`` " +"directory (including the ``RECORD`` file itself) must be listed. Directories " +"should not be listed." msgstr "" +"もし ``RECORD`` ファイルが存在するなら、 ``RECORD`` に記入された ``.py`` ファ" +"イルに対応する ``.pyc`` ファイルを記入することはオプションですが、それを除い" +"てそのプロジェクトからインストールされたファイルの全てについて列挙していなけ" +"ればなりません。特に、 ``.dist-info`` ディレクトリ の内容 (``RECORD`` ファイ" +"ル自身を含む) については、書いておかなければなりません。ディレクトリについて" +"は記入してはなりません。" -#: ../source/specifications/simple-repository-api.rst:189 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" -"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" -"yanked`` attribute for it." +"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 "" +"パッケージを完全にアンインストールするためには、ツールは、 ``RECORD`` に列挙" +"された全てのファイルと、 ``.py`` ファイルに対応する (あらゆる最適化状態の) " +"``.pyc`` ファイルと、アンインストールによって空になったすべてのディレクトリを" +"削除する必要があります。" -#: ../source/specifications/simple-repository-api.rst:195 -msgid "Versioning PyPI's Simple API" -msgstr "" +#: ../source/specifications/recording-installed-packages.rst:140 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "ありうる ``RECORD`` ファイルの一部を切り出した例をここに掲げます::" -#: ../source/specifications/simple-repository-api.rst:197 +#: ../source/specifications/recording-installed-packages.rst:159 msgid "" -"This spec proposes the inclusion of a meta tag on the responses of every " -"successful request to a simple API page, which contains a name attribute of " -"\"pypi:repository-version\", and a content that is a :ref:`version " -"specifiers specification ` compatible version number, " -"which is further constrained to ONLY be Major.Minor, and none of the " -"additional features supported by :ref:`the version specifiers specification " -"`." +"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 " +"apply to tools that rely on other sources of information, such as system " +"package managers in Linux distros.)" msgstr "" +"``RECORD`` ファイルが存在しない場合、 ``.dist-info`` に依存するツールは、アン" +"インストールやアップグレードを試みてはなりません。(この制約は、 Linux ディス" +"トロにおけるシステムのパッケージ管理機構のような、それ以外の情報源に依存する" +"ツールには適用されません。)" -#: ../source/specifications/simple-repository-api.rst:205 -msgid "This would end up looking like::" +#: ../source/specifications/recording-installed-packages.rst:166 +msgid "" +"It is *strongly discouraged* for an installed package to modify itself (e." +"g., store cache files under its namespace in ``site-packages``). Changes " +"inside ``site-packages`` should be left to specialized installer tools such " +"as pip. If a package is nevertheless modified in this way, then the " +"``RECORD`` must be updated, otherwise uninstalling the package will leave " +"unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/simple-repository-api.rst:209 -msgid "When interpreting the repository version:" -msgstr "" +#: ../source/specifications/recording-installed-packages.rst:175 +msgid "The INSTALLER file" +msgstr "INSTALLER ファイル" -#: ../source/specifications/simple-repository-api.rst:211 +#: ../source/specifications/recording-installed-packages.rst:177 msgid "" -"Incrementing the major version is used to signal a backwards incompatible " -"change such that existing clients would no longer be expected to be able to " -"meaningfully use the API." +"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, " +"``INSTALLER`` should contain the command name. Otherwise, it should contain " +"a printable ASCII string." msgstr "" +"もし存在するなら、 ``INSTALLER`` は、プロジェクトのインストールに使われたツー" +"ルを名指しする１行のテキストファイルです。インストーラがコマンドラインから起" +"動されるなら、 ``INSTALLER`` はそのコマンドの名前を含んでいるべきです。そうで" +"なければ印刷可能な ASCII 文字を含んでいるべきです。" -#: ../source/specifications/simple-repository-api.rst:214 -msgid "" -"Incrementing the minor version is used to signal a backwards compatible " -"change such that existing clients would still be expected to be able to " -"meaningfully use the API." +#: ../source/specifications/recording-installed-packages.rst:183 +msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" +"ファイルは、0個またはそれ以上の ASCII 空白文字で終端することができます。" -#: ../source/specifications/simple-repository-api.rst:218 +#: ../source/specifications/recording-installed-packages.rst:185 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "``INSTALLER`` ファイルについて、二つの可能な例を示します::" + +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" -"It is left up to the discretion of any future specs as to what specifically " -"constitutes a backwards incompatible vs compatible change beyond the broad " -"suggestion that existing clients will be able to \"meaningfully\" continue " -"to use the API, and can include adding, modifying, or removing existing " -"features." +"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 " +"suggest that the tool named in ``INSTALLER`` may be able to do the " +"uninstallation." msgstr "" +"この値は情報提供目的にのみ使用されるべきです。例えば、あるツールでプロジェク" +"トのアンインストールをしようとしたが ``RECORD`` ファイルを見つけられなかった" +"場合には、そのツールは ``INSTALLER`` ファイルに書いてある (別の) ツールを使え" +"ばアンインストールができるかもしれないと示唆しても構いません。" -#: ../source/specifications/simple-repository-api.rst:224 +#: ../source/specifications/recording-installed-packages.rst:200 +msgid "The entry_points.txt file" +msgstr "entry_points.txt ファイル" + +#: ../source/specifications/recording-installed-packages.rst:202 msgid "" -"It is expectation of this spec that the major version will never be " -"incremented, and any future major API evolutions would utilize a different " -"mechanism for API evolution. However the major version is included to " -"disambiguate with future versions (e.g. a hypothetical simple api v2 that " -"lived at /v2/, but which would be confusing if the repository-version was " -"set to a version >= 2)." +"This file MAY be created by installers to indicate when packages contain " +"components intended for discovery and use by other code, including console " +"scripts and other applications that the installer has made available for " +"execution." msgstr "" +"インストーラが (他者から) 実行できる状態にするコンソールスクリプトや他のアプ" +"リケーションを含めて、 (他者から) 発見されたり他のソースコードから利用された" +"りすることを意図したコンポーネントを当該パッケージが含んでいる場合には、イン" +"ストーラがその由を表示するためにこのファイルを作っても構いません。" -#: ../source/specifications/simple-repository-api.rst:231 +#: ../source/specifications/recording-installed-packages.rst:207 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "その詳細な仕様は :ref:`entry-points` にあります。" + +#: ../source/specifications/recording-installed-packages.rst:211 +msgid "The direct_url.json file" +msgstr "direct_url.json ファイル" + +#: ../source/specifications/recording-installed-packages.rst:213 msgid "" -"This spec sets the current API version to \"1.0\", and expects that future " -"specs that further evolve the simple API will increment the minor version " -"number." +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" +"このファイルは、要求事項が指定するダイレクト URL (VCS の URL を含む) から配布" +"物をインストールする際に、インストーラによって生成されなければなりません。" -#: ../source/specifications/simple-repository-api.rst:237 -#: ../source/specifications/simple-repository-api.rst:957 -#, fuzzy -msgid "Clients" -msgstr "内容" +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "その詳細な仕様は :ref:`direct-url` にあります。" -#: ../source/specifications/simple-repository-api.rst:239 +#: ../source/specifications/recording-installed-packages.rst:223 +msgid "Intentionally preventing changes to installed packages" +msgstr "インストール済みのパッケージ群への変更を意図的に防ぐ" + +#: ../source/specifications/recording-installed-packages.rst:225 msgid "" -"Clients interacting with the simple API **SHOULD** introspect each response " -"for the repository version, and if that data does not exist **MUST** assume " -"that it is version 1.0." +"In some cases (such as when needing to manage external dependencies in " +"addition to Python ecosystem dependencies), it is desirable for a tool that " +"installs packages into a Python environment to ensure that other tools are " +"not used to uninstall or otherwise modify that installed package, as doing " +"so may cause compatibility problems with the wider environment." +msgstr "" +"(Python エコシステムでの依存関係に加えて外部の依存関係を管理する必要がある場" +"合など) いくつかの場合には、 Python 環境にパッケージをインストールするツール" +"が、そのインストール済みパッケージを他のツールがアンインストールも修正もして" +"いないことを、もしそんなことをしていればより広範な環境に互換性問題を引き起こ" +"しかねないので、しっかりと確認することが望ましいです。" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "To achieve this, affected tools should take the following steps:" msgstr "" +"これを達成するために、影響を被るツール群は次のような段階を踏むべきです:" -#: ../source/specifications/simple-repository-api.rst:243 +#: ../source/specifications/recording-installed-packages.rst:233 msgid "" -"When encountering a major version greater than expected, clients **MUST** " -"hard fail with an appropriate error message for the user." +"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 " +"tool itself needs the information, or omitting the file entirely if the " +"package contents are tracked and managed via other means)" msgstr "" +"他のツール類を経由した変更を抑止するために、``RECORD`` ファイルを別の名前にす" +"るか、削除するか (このファイル内の情報が必要なら、例えば標準的でない名前の " +"``RECORD.tool`` というファイルを作成するために拡張子を追加すること、あるい" +"は、パッケージの内容物を他の手段で追跡・管理しているのであればファイルを完全" +"に除外しておくこと) してください。" -#: ../source/specifications/simple-repository-api.rst:246 +#: ../source/specifications/recording-installed-packages.rst:237 msgid "" -"When encountering a minor version greater than expected, clients **SHOULD** " -"warn users with an appropriate message." +"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 "" +"そのパッケージを管理するのに使用されるべきツールの名前を示すように" +"``INSTALLER`` ファイルを書いてください (これによって、 ``RECORD`` を参照でき" +"るツール群が影響を被るパッケージを修正するように言われた時により良いエラー通" +"知を提供できます)" -#: ../source/specifications/simple-repository-api.rst:249 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" -"Clients **MAY** still continue to use feature detection in order to " -"determine what features a repository uses." +"Python runtime providers may also prevent inadvertent modification of " +"platform provided packages by modifying the default Python package " +"installation scheme to use a location other than that used by platform " +"provided packages (while also ensuring both locations appear on the default " +"Python import path)." msgstr "" +"Python ランタイムの提供者は、デフォルトの Python パッケージのインストレーショ" +"ンスキームを修正してプラットフォームが提供するパッケージ群で使われるものとは" +"別の場所を使うようにすることで、プラットフォームが提供するパッケージ群を意図" +"せずに修正してしまうことを防いでも構いません。" -#: ../source/specifications/simple-repository-api.rst:255 -msgid "Serve Distribution Metadata in the Simple Repository API" +#: ../source/specifications/recording-installed-packages.rst:246 +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:" +"`externally-managed-environments`" msgstr "" +"いくつかの環境では、 Python 特有のツール群を経由した追加パッケージのインス" +"トールさえもブロックすることが望ましいかもしれません。このようなケースについ" +"ては :ref:`外部から管理される環境 ` を参照し" +"てください" -#: ../source/specifications/simple-repository-api.rst:257 +#: ../source/specifications/recording-installed-packages.rst:254 msgid "" -"In a simple repository's project page, each anchor tag pointing to a " -"distribution **MAY** have a ``data-dist-info-metadata`` attribute. The " -"presence of the attribute indicates the distribution represented by the " -"anchor tag **MUST** contain a Core Metadata file that will not be modified " -"when the distribution is processed and/or installed." +"June 2009: The original version of this specification was approved through :" +"pep:`376`. At the time, it was known as the *Database of Installed Python " +"Distributions*." msgstr "" -#: ../source/specifications/simple-repository-api.rst:263 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" -"If a ``data-dist-info-metadata`` attribute is present, the repository " -"**MUST** serve the distribution's Core Metadata file alongside the " -"distribution with a ``.metadata`` appended to the distribution's file name. " -"For example, the Core Metadata of a distribution served at ``/files/" -"distribution-1.0-py3.none.any.whl`` would be located at ``/files/" -"distribution-1.0-py3.none.any.whl.metadata``. This is similar to how :ref:" -"`the base HTML API specification ` specifies the " -"GPG signature file's location." +"March 2020: The specification of the ``direct_url.json`` file was approved " +"through :pep:`610`. It is only mentioned on this page; see :ref:`direct-url` " +"for the full definition." msgstr "" -#: ../source/specifications/simple-repository-api.rst:272 +#: ../source/specifications/recording-installed-packages.rst:260 msgid "" -"The repository **SHOULD** provide the hash of the Core Metadata file as the " -"``data-dist-info-metadata`` attribute's value using the syntax " -"``=``, where ```` is the lower cased name of " -"the hash function used, and ```` is the hex encoded digest. The " -"repository **MAY** use ``true`` as the attribute's value if a hash is " -"unavailable." +"September 2020: Various amendments and clarifications were approved through :" +"pep:`627`." msgstr "" -#: ../source/specifications/simple-repository-api.rst:280 +#: ../source/specifications/section-distribution-formats.rst:3 +msgid "Package Distribution File Formats" +msgstr "パッケージ配布物のファイルフォーマット" + +#: ../source/specifications/section-distribution-metadata.rst:3 +msgid "Package Distribution Metadata" +msgstr "パッケージ配布物のメタデータ" + +#: ../source/specifications/section-installation-metadata.rst:3 #, fuzzy -msgid "Backwards Compatibility" -msgstr "ABI の互換性" +msgid "Package Installation Metadata" +msgstr "パッケージのインストール環境のメタデータ" -#: ../source/specifications/simple-repository-api.rst:282 -msgid "" -"If an anchor tag lacks the ``data-dist-info-metadata`` attribute, tools are " -"expected to revert to their current behaviour of downloading the " -"distribution to inspect the metadata." -msgstr "" +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "パッケージインデックスのインタフェース" -#: ../source/specifications/simple-repository-api.rst:286 -msgid "" -"Older tools not supporting the new ``data-dist-info-metadata`` attribute are " -"expected to ignore the attribute and maintain their current behaviour of " -"downloading the distribution to inspect the metadata. This is similar to how " -"prior ``data-`` attribute additions expect existing tools to operate." -msgstr "" +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "シンプルなリポジトリ API" -#: ../source/specifications/simple-repository-api.rst:295 -msgid "JSON-based Simple API for Python Package Indexes" +#: ../source/specifications/simple-repository-api.rst:8 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: HTML and JSON." msgstr "" +"利用可能なパッケージバージョンを問い合わせたり、インデックスサーバからパッ" +"ケージを取り出したりするためのインターフェースは、二つの形式: HTML と JSON で" +"もたらされます。" -#: ../source/specifications/simple-repository-api.rst:297 -msgid "" -"To enable response parsing with only the standard library, this spec " -"specifies that all responses (besides the files themselves, and the HTML " -"responses from :ref:`the base HTML API specification `) should be serialized using `JSON `_." +#: ../source/specifications/simple-repository-api.rst:15 +msgid "Base HTML API" msgstr "" -#: ../source/specifications/simple-repository-api.rst:302 +#: ../source/specifications/simple-repository-api.rst:17 msgid "" -"To enable zero configuration discovery and to minimize the amount of " -"additional HTTP requests, this spec extends :ref:`the base HTML API " -"specification ` such that all of the API " -"endpoints (other than the files themselves) will utilize HTTP content " -"negotiation to allow client and server to select the correct serialization " -"format to serve, i.e. either HTML or JSON." +"A repository that implements the simple API is defined by its base URL, this " +"is the top level URL that all additional URLs are below. The API is named " +"the \"simple\" repository due to the fact that PyPI's base URL is ``https://" +"pypi.org/simple/``." msgstr "" -#: ../source/specifications/simple-repository-api.rst:312 +#: ../source/specifications/simple-repository-api.rst:22 msgid "" -"Versioning will adhere to :ref:`the API versioning specification ` format (``Major.Minor``), which has defined the " -"existing HTML responses to be ``1.0``. Since this spec does not introduce " -"new features into the API, rather it describes a different serialization " -"format for the existing features, this spec does not change the existing " -"``1.0`` version, and instead just describes how to serialize that into JSON." +"All subsequent URLs in this document will be relative to this base URL (so " +"given PyPI's URL, a URL of ``/foo/`` would be ``https://pypi.org/simple/foo/" +"``." msgstr "" -#: ../source/specifications/simple-repository-api.rst:319 +#: ../source/specifications/simple-repository-api.rst:27 msgid "" -"Similar to :ref:`the API versioning specification `, the major version number **MUST** be incremented if any " -"changes to the new format would result in no longer being able to expect " -"existing clients to meaningfully understand the format." +"Within a repository, the root URL (``/`` for this spec which represents the " +"base URL) **MUST** be a valid HTML5 page with a single anchor element per " +"project in the repository. The text of the anchor tag **MUST** be the name " +"of the project and the href attribute **MUST** link to the URL for that " +"particular project. As an example::" msgstr "" -#: ../source/specifications/simple-repository-api.rst:325 +#: ../source/specifications/simple-repository-api.rst:41 msgid "" -"Likewise, the minor version **MUST** be incremented if features are added or " -"removed from the format, but existing clients would be expected to continue " -"to meaningfully understand the format." +"Below the root URL is another URL for each individual project contained " +"within a repository. The format of this URL is ``//`` where the " +"```` is replaced by the normalized name for that project, so a " +"project named \"HolyGrail\" would have a URL like ``/holygrail/``. This URL " +"must respond with a valid HTML5 page with a single anchor element per file " +"for the project. The href attribute **MUST** be a URL that links to the " +"location of the file for download, and the text of the anchor tag **MUST** " +"match the final path component (the filename) of the URL. The URL **SHOULD** " +"include a hash in the form of a URL fragment with the following syntax: " +"``#=``, where ```` is the lowercase name of " +"the hash function (such as ``sha256``) and ```` is the hex " +"encoded digest." msgstr "" -#: ../source/specifications/simple-repository-api.rst:329 +#: ../source/specifications/simple-repository-api.rst:53 msgid "" -"Changes that would not result in existing clients being unable to " -"meaningfully understand the format and which do not represent features being " -"added or removed may occur without changing the version number." +"In addition to the above, the following constraints are placed on the API:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:333 +#: ../source/specifications/simple-repository-api.rst:55 msgid "" -"This is intentionally vague, as this spec believes it is best left up to " -"future specs that make any changes to the API to investigate and decide " -"whether or not that change should increment the major or minor version." +"All URLs which respond with an HTML5 page **MUST** end with a ``/`` and the " +"repository **SHOULD** redirect the URLs without a ``/`` to add a ``/`` to " +"the end." msgstr "" -#: ../source/specifications/simple-repository-api.rst:337 +#: ../source/specifications/simple-repository-api.rst:59 msgid "" -"Future versions of the API may add things that can only be represented in a " -"subset of the available serializations of that version. All serializations " -"version numbers, within a major version, **SHOULD** be kept in sync, but the " -"specifics of how a feature serializes into each format may differ, including " -"whether or not that feature is present at all." +"URLs may be either absolute or relative as long as they point to the correct " +"location." msgstr "" -#: ../source/specifications/simple-repository-api.rst:343 +#: ../source/specifications/simple-repository-api.rst:62 msgid "" -"It is the intent of this spec that the API should be thought of as URL " -"endpoints that return data, whose interpretation is defined by the version " -"of that data, and then serialized into the target serialization format." +"There are no constraints on where the files must be hosted relative to the " +"repository." msgstr "" -#: ../source/specifications/simple-repository-api.rst:351 -#, fuzzy -msgid "JSON Serialization" -msgstr "正規化" - -#: ../source/specifications/simple-repository-api.rst:353 +#: ../source/specifications/simple-repository-api.rst:65 msgid "" -"The URL structure from :ref:`the base HTML API specification ` still applies, as this spec only adds an additional " -"serialization format for the already existing API." +"There may be any other HTML elements on the API pages as long as the " +"required anchor elements exist." msgstr "" -#: ../source/specifications/simple-repository-api.rst:357 +#: ../source/specifications/simple-repository-api.rst:68 msgid "" -"The following constraints apply to all JSON serialized responses described " -"in this spec:" +"Repositories **MAY** redirect unnormalized URLs to the canonical normalized " +"URL (e.g. ``/Foobar/`` may redirect to ``/foobar/``), however clients **MUST " +"NOT** rely on this redirection and **MUST** request the normalized URL." msgstr "" -#: ../source/specifications/simple-repository-api.rst:360 +#: ../source/specifications/simple-repository-api.rst:73 msgid "" -"All JSON responses will *always* be a JSON object rather than an array or " -"other type." +"Repositories **SHOULD** choose a hash function from one of the ones " +"guaranteed to be available via the :py:mod:`hashlib` module in the Python " +"standard library (currently ``md5``, ``sha1``, ``sha224``, ``sha256``, " +"``sha384``, ``sha512``). The current recommendation is to use ``sha256``." msgstr "" -#: ../source/specifications/simple-repository-api.rst:363 +#: ../source/specifications/simple-repository-api.rst:78 msgid "" -"While JSON doesn't natively support an URL type, any value that represents " -"an URL in this API may be either absolute or relative as long as they point " -"to the correct location. If relative, they are relative to the current URL " -"as if it were HTML." +"If there is a GPG signature for a particular distribution file it **MUST** " +"live alongside that file with the same name with a ``.asc`` appended to it. " +"So if the file ``/packages/HolyGrail-1.0.tar.gz`` existed and had an " +"associated signature, the signature would be located at ``/packages/" +"HolyGrail-1.0.tar.gz.asc``." msgstr "" -#: ../source/specifications/simple-repository-api.rst:368 +#: ../source/specifications/simple-repository-api.rst:84 msgid "" -"Additional keys may be added to any dictionary objects in the API responses " -"and clients **MUST** ignore keys that they don't understand." +"A repository **MAY** include a ``data-gpg-sig`` attribute on a file link " +"with a value of either ``true`` or ``false`` to indicate whether or not " +"there is a GPG signature. Repositories that do this **SHOULD** include it on " +"every link." msgstr "" -#: ../source/specifications/simple-repository-api.rst:371 +#: ../source/specifications/simple-repository-api.rst:88 msgid "" -"All JSON responses will have a ``meta`` key, which contains information " -"related to the response itself, rather than the content of the response." +"A repository **MAY** include a ``data-requires-python`` attribute on a file " +"link. This exposes the :ref:`core-metadata-requires-python` metadata field " +"for the corresponding release. Where this is present, installer tools " +"**SHOULD** ignore the download when installing to a Python version that " +"doesn't satisfy the requirement. For example::" msgstr "" -#: ../source/specifications/simple-repository-api.rst:374 +#: ../source/specifications/simple-repository-api.rst:96 msgid "" -"All JSON responses will have a ``meta.api-version`` key, which will be a " -"string that contains the :ref:`API versioning specification ` ``Major.Minor`` version number, with the same " -"fail/warn semantics as defined in :ref:`the API versioning specification " -"`." +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." msgstr "" -#: ../source/specifications/simple-repository-api.rst:380 +#: ../source/specifications/simple-repository-api.rst:100 +#, fuzzy +msgid "Normalized Names" +msgstr "正当な非正規化名" + +#: ../source/specifications/simple-repository-api.rst:102 msgid "" -"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +"This spec references the concept of a \"normalized\" project name. As per :" +"ref:`the name normalization specification ` the only " +"valid characters in a name are the ASCII alphabet, ASCII numbers, ``.``, ``-" +"``, and ``_``. 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/simple-repository-api.rst:385 -#, fuzzy -msgid "Project List" -msgstr "プロジェクト" +#: ../source/specifications/simple-repository-api.rst:117 +msgid "Adding \"Yank\" Support to the Simple API" +msgstr "" -#: ../source/specifications/simple-repository-api.rst:387 +#: ../source/specifications/simple-repository-api.rst:119 msgid "" -"The root URL ``/`` for this spec (which represents the base URL) will be a " -"JSON encoded dictionary which has a two keys:" +"Links in the simple repository **MAY** have a ``data-yanked`` attribute " +"which may have no value, or may have an arbitrary string as a value. The " +"presence of a ``data-yanked`` attribute **SHOULD** be interpreted as " +"indicating that the file pointed to by this particular link has been " +"\"Yanked\", and should not generally be selected by an installer, except " +"under specific scenarios." msgstr "" -#: ../source/specifications/simple-repository-api.rst:390 +#: ../source/specifications/simple-repository-api.rst:126 msgid "" -"``projects``: An array where each entry is a dictionary with a single key, " -"``name``, which represents string of the project name." +"The value of the ``data-yanked`` attribute, if present, is an arbitrary " +"string that represents the reason for why the file has been yanked. Tools " +"that process the simple repository API **MAY** surface this string to end " +"users." msgstr "" -#: ../source/specifications/simple-repository-api.rst:391 -#: ../source/specifications/simple-repository-api.rst:440 +#: ../source/specifications/simple-repository-api.rst:131 msgid "" -"``meta``: The general response metadata as `described earlier `__." +"The yanked attribute is not immutable once set, and may be rescinded in the " +"future (and once rescinded, may be reset as well). Thus API users **MUST** " +"be able to cope with a yanked file being \"unyanked\" (and even yanked " +"again)." msgstr "" -#: ../source/specifications/simple-repository-api.rst:393 -#: ../source/specifications/simple-repository-api.rst:499 +#: ../source/specifications/simple-repository-api.rst:138 #, fuzzy -msgid "As an example:" -msgstr "完全な例" +msgid "Installers" +msgstr "インストーラ" -#: ../source/specifications/simple-repository-api.rst:410 +#: ../source/specifications/simple-repository-api.rst:140 msgid "" -"The ``name`` field is the same as the one from :ref:`the base HTML API " -"specification `, which does not specify whether " -"it is the non-normalized display name or the normalized name. In practice " -"different implementations of these specs are choosing differently here, so " -"relying on it being either non-normalized or normalized is relying on an " -"implementation detail of the repository in question." +"The desirable experience for users is that once a file is yanked, when a " +"human being is currently trying to directly install a yanked file, that it " +"fails as if that file had been deleted. However, when a human did that " +"awhile ago, and now a computer is just continuing to mechanically follow the " +"original order to install the now yanked file, then it acts as if it had not " +"been yanked." msgstr "" -#: ../source/specifications/simple-repository-api.rst:420 +#: ../source/specifications/simple-repository-api.rst:147 msgid "" -"While the ``projects`` key is an array, and thus is required to be in some " -"kind of an order, neither :ref:`the base HTML API specification ` nor this spec requires any specific ordering nor that " -"the ordering is consistent from one request to the next. Mentally this is " -"best thought of as a set, but both JSON and HTML lack the functionality to " -"have sets." +"An installer **MUST** ignore yanked releases, if the selection constraints " +"can be satisfied with a non-yanked version, and **MAY** refuse to use a " +"yanked release even if it means that the request cannot be satisfied at all. " +"An implementation **SHOULD** choose a policy that follows the spirit of the " +"intention above, and that prevents \"new\" dependencies on yanked releases/" +"files." msgstr "" -#: ../source/specifications/simple-repository-api.rst:429 -#, fuzzy -msgid "Project Detail" -msgstr "プロジェクト名" - -#: ../source/specifications/simple-repository-api.rst:431 +#: ../source/specifications/simple-repository-api.rst:154 msgid "" -"The format of this URL is ``//`` where the ```` is " -"replaced by the :ref:`the base HTML API specification ` normalized name for that project, so a project named \"Silly_Walk\" " -"would have a URL like ``/silly-walk/``." +"What this means is left up to the specific installer, to decide how to best " +"fit into the overall usage of their installer. However, there are two " +"suggested approaches to take:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:158 msgid "" -"This URL must respond with a JSON encoded dictionary that has three keys:" +"Yanked files are always ignored, unless they are the only file that matches " +"a version specifier that \"pins\" to an exact version using either ``==`` " +"(without any modifiers that make it a range, such as ``.*``) or ``===``. " +"Matching this version specifier should otherwise be done as per :ref:`the " +"version specifiers specification ` for things like local " +"versions, zero padding, etc." msgstr "" -#: ../source/specifications/simple-repository-api.rst:438 -#, fuzzy -msgid "``name``: The normalized name of the project." -msgstr "プロジェクトの名前。" - -#: ../source/specifications/simple-repository-api.rst:439 +#: ../source/specifications/simple-repository-api.rst:165 msgid "" -"``files``: A list of dictionaries, each one representing an individual file." +"Yanked files are always ignored, unless they are the only file that matches " +"what a lock file (such as ``Pipfile.lock`` or ``poetry.lock``) specifies to " +"be installed. In this case, a yanked file **SHOULD** not be used when " +"creating or updating a lock file from some input file or command." msgstr "" -#: ../source/specifications/simple-repository-api.rst:442 -msgid "Each individual file dictionary has the following keys:" +#: ../source/specifications/simple-repository-api.rst:171 +msgid "" +"Regardless of the specific strategy that an installer chooses for deciding " +"when to install yanked files, an installer **SHOULD** emit a warning when it " +"does decide to install a yanked file. That warning **MAY** utilize the value " +"of the ``data-yanked`` attribute (if it has a value) to provide more " +"specific feedback to the user about why that file had been yanked." msgstr "" -#: ../source/specifications/simple-repository-api.rst:444 -msgid "``filename``: The filename that is being represented." +#: ../source/specifications/simple-repository-api.rst:179 +msgid "Mirrors" msgstr "" -#: ../source/specifications/simple-repository-api.rst:445 -msgid "``url``: The URL that the file can be fetched from." +#: ../source/specifications/simple-repository-api.rst:181 +msgid "Mirrors can generally treat yanked files one of two ways:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:446 -#, fuzzy +#: ../source/specifications/simple-repository-api.rst:183 msgid "" -"``hashes``: A dictionary mapping a hash name to a hex encoded digest of the " -"file. Multiple hashes can be included, and it is up to the client to decide " -"what to do with multiple hashes (it may validate all of them or a subset of " -"them, or nothing at all). These hash names **SHOULD** always be normalized " -"to be lowercase." +"They may choose to omit them from their simple repository API completely, " +"providing a view over the repository that shows only \"active\", unyanked " +"files." msgstr "" -"複数のハッシュ値を含めることが可能で、そのような複数のハッシュ値を使って何を" -"するか (すべてのハッシュ値を検証しても一部だけを検証しても構いませんし、何も" -"しなくても構いません) については利用する側次第です。" -#: ../source/specifications/simple-repository-api.rst:451 +#: ../source/specifications/simple-repository-api.rst:186 msgid "" -"The ``hashes`` dictionary **MUST** be present, even if no hashes are " -"available for the file, however it is **HIGHLY** recommended that at least " -"one secure, guaranteed-to-be-available hash is always included." +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." msgstr "" -#: ../source/specifications/simple-repository-api.rst:455 -#, fuzzy +#: ../source/specifications/simple-repository-api.rst:189 msgid "" -"By default, any hash algorithm available via :py:mod:`hashlib` (specifically " -"any that can be passed to :py:func:`hashlib.new()` and do not require " -"additional parameters) can be used as a key for the hashes dictionary. At " -"least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " -"**SHOULD** always be included. At the time of this spec, ``sha256`` " -"specifically is recommended." +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." msgstr "" -"``hash lib`` 経由で利用可能なハッシュアルゴリズム (とりわけ、 ``hashlib." -"new()`` に渡すことができて、かつ、追加的なパラメータを必要としないもの) はど" -"れでも、ハッシュ値を格納する辞書のキーとして用いることができます。 ``hashlib." -"algorithms_garanteed`` から安全なアルゴリズムを少なくともひとつ選択して (訳" -"注、ハッシュ値格納用辞書に) 含めるべきです。執筆時点では、 ``sha256`` が特に" -"推奨されています。" -#: ../source/specifications/simple-repository-api.rst:460 -msgid "" -"``requires-python``: An **optional** key that exposes the :ref:`core-" -"metadata-requires-python` metadata field. Where this is present, installer " -"tools **SHOULD** ignore the download when installing to a Python version " -"that doesn't satisfy the requirement." +#: ../source/specifications/simple-repository-api.rst:195 +msgid "Versioning PyPI's Simple API" msgstr "" -#: ../source/specifications/simple-repository-api.rst:466 +#: ../source/specifications/simple-repository-api.rst:197 msgid "" -"Unlike ``data-requires-python`` in :ref:`the base HTML API specification " -"`, the ``requires-python`` key does not require " -"any special escaping other than anything JSON does naturally." +"This spec proposes the inclusion of a meta tag on the responses of every " +"successful request to a simple API page, which contains a name attribute of " +"\"pypi:repository-version\", and a content that is a :ref:`version " +"specifiers specification ` compatible version number, " +"which is further constrained to ONLY be Major.Minor, and none of the " +"additional features supported by :ref:`the version specifiers specification " +"`." msgstr "" -#: ../source/specifications/simple-repository-api.rst:469 -msgid "" -"``dist-info-metadata``: An **optional** key that indicates that metadata for " -"this file is available, via the same location as specified in :ref:`the API " -"metadata file specification ` " -"(``{file_url}.metadata``). Where this is present, it **MUST** be either a " -"boolean to indicate if the file has an associated metadata file, or a " -"dictionary mapping hash names to a hex encoded digest of the metadata's hash." +#: ../source/specifications/simple-repository-api.rst:205 +msgid "This would end up looking like::" msgstr "" -#: ../source/specifications/simple-repository-api.rst:477 -msgid "" -"When this is a dictionary of hashes instead of a boolean, then all the same " -"requirements and recommendations as the ``hashes`` key hold true for this " -"key as well." +#: ../source/specifications/simple-repository-api.rst:209 +msgid "When interpreting the repository version:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:481 +#: ../source/specifications/simple-repository-api.rst:211 msgid "" -"If this key is missing then the metadata file may or may not exist. If the " -"key value is truthy, then the metadata file is present, and if it is falsey " -"then it is not." +"Incrementing the major version is used to signal a backwards incompatible " +"change such that existing clients would no longer be expected to be able to " +"meaningfully use the API." msgstr "" -#: ../source/specifications/simple-repository-api.rst:485 +#: ../source/specifications/simple-repository-api.rst:214 msgid "" -"It is recommended that servers make the hashes of the metadata file " -"available if possible." +"Incrementing the minor version is used to signal a backwards compatible " +"change such that existing clients would still be expected to be able to " +"meaningfully use the API." msgstr "" -#: ../source/specifications/simple-repository-api.rst:487 +#: ../source/specifications/simple-repository-api.rst:218 msgid "" -"``gpg-sig``: An **optional** key that acts a boolean to indicate if the file " -"has an associated GPG signature or not. The URL for the signature file " -"follows what is specified in :ref:`the base HTML API specification ` (``{file_url}.asc``). If this key does not exist, then " -"the signature may or may not exist." +"It is left up to the discretion of any future specs as to what specifically " +"constitutes a backwards incompatible vs compatible change beyond the broad " +"suggestion that existing clients will be able to \"meaningfully\" continue " +"to use the API, and can include adding, modifying, or removing existing " +"features." msgstr "" -#: ../source/specifications/simple-repository-api.rst:492 +#: ../source/specifications/simple-repository-api.rst:224 msgid "" -"``yanked``: An **optional** key which may be either a boolean to indicate if " -"the file has been yanked, or a non empty, but otherwise arbitrary, string to " -"indicate that a file has been yanked with a specific reason. If the " -"``yanked`` key is present and is a truthy value, then it **SHOULD** be " -"interpreted as indicating that the file pointed to by the ``url`` field has " -"been \"Yanked\" as per :ref:`the API yank specification `." +"It is expectation of this spec that the major version will never be " +"incremented, and any future major API evolutions would utilize a different " +"mechanism for API evolution. However the major version is included to " +"disambiguate with future versions (e.g. a hypothetical simple api v2 that " +"lived at /v2/, but which would be confusing if the repository-version was " +"set to a version >= 2)." msgstr "" -#: ../source/specifications/simple-repository-api.rst:529 +#: ../source/specifications/simple-repository-api.rst:231 msgid "" -"While the ``files`` key is an array, and thus is required to be in some kind " -"of an order, neither :ref:`the base HTML API specification ` nor this spec requires any specific ordering nor that " -"the ordering is consistent from one request to the next. Mentally this is " -"best thought of as a set, but both JSON and HTML lack the functionality to " -"have sets." +"This spec sets the current API version to \"1.0\", and expects that future " +"specs that further evolve the simple API will increment the minor version " +"number." msgstr "" -#: ../source/specifications/simple-repository-api.rst:538 +#: ../source/specifications/simple-repository-api.rst:237 +#: ../source/specifications/simple-repository-api.rst:957 #, fuzzy -msgid "Content-Types" +msgid "Clients" msgstr "内容" -#: ../source/specifications/simple-repository-api.rst:540 +#: ../source/specifications/simple-repository-api.rst:239 msgid "" -"This spec proposes that all responses from the Simple API will have a " -"standard content type that describes what the response is (a Simple API " -"response), what version of the API it represents, and what serialization " -"format has been used." +"Clients interacting with the simple API **SHOULD** introspect each response " +"for the repository version, and if that data does not exist **MUST** assume " +"that it is version 1.0." msgstr "" -#: ../source/specifications/simple-repository-api.rst:544 -msgid "The structure of this content type will be:" +#: ../source/specifications/simple-repository-api.rst:243 +msgid "" +"When encountering a major version greater than expected, clients **MUST** " +"hard fail with an appropriate error message for the user." msgstr "" -#: ../source/specifications/simple-repository-api.rst:550 +#: ../source/specifications/simple-repository-api.rst:246 msgid "" -"Since only major versions should be disruptive to clients attempting to " -"understand one of these API responses, only the major version will be " -"included in the content type, and will be prefixed with a ``v`` to clarify " -"that it is a version number." +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." msgstr "" -#: ../source/specifications/simple-repository-api.rst:555 -msgid "Which means that for the existing 1.0 API, the content types would be:" +#: ../source/specifications/simple-repository-api.rst:249 +msgid "" +"Clients **MAY** still continue to use feature detection in order to " +"determine what features a repository uses." msgstr "" -#: ../source/specifications/simple-repository-api.rst:557 -msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +#: ../source/specifications/simple-repository-api.rst:255 +msgid "Serve Distribution Metadata in the Simple Repository API" msgstr "" -#: ../source/specifications/simple-repository-api.rst:558 -msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +#: ../source/specifications/simple-repository-api.rst:257 +msgid "" +"In a simple repository's project page, each anchor tag pointing to a " +"distribution **MAY** have a ``data-dist-info-metadata`` attribute. The " +"presence of the attribute indicates the distribution represented by the " +"anchor tag **MUST** contain a Core Metadata file that will not be modified " +"when the distribution is processed and/or installed." msgstr "" -#: ../source/specifications/simple-repository-api.rst:560 +#: ../source/specifications/simple-repository-api.rst:263 msgid "" -"In addition to the above, a special \"meta\" version is supported named " -"``latest``, whose purpose is to allow clients to request the absolute latest " -"version, without having to know ahead of time what that version is. It is " -"recommended however, that clients be explicit about what versions they " -"support." +"If a ``data-dist-info-metadata`` attribute is present, the repository " +"**MUST** serve the distribution's Core Metadata file alongside the " +"distribution with a ``.metadata`` appended to the distribution's file name. " +"For example, the Core Metadata of a distribution served at ``/files/" +"distribution-1.0-py3.none.any.whl`` would be located at ``/files/" +"distribution-1.0-py3.none.any.whl.metadata``. This is similar to how :ref:" +"`the base HTML API specification ` specifies the " +"GPG signature file's location." msgstr "" -#: ../source/specifications/simple-repository-api.rst:565 +#: ../source/specifications/simple-repository-api.rst:272 msgid "" -"To support existing clients which expect the existing :ref:`the base HTML " -"API specification ` API responses to use the " -"``text/html`` content type, this spec further defines ``text/html`` as an " -"alias for the ``application/vnd.pypi.simple.v1+html`` content type." +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-dist-info-metadata`` attribute's value using the syntax " +"``=``, where ```` is the lower cased name of " +"the hash function used, and ```` is the hex encoded digest. The " +"repository **MAY** use ``true`` as the attribute's value if a hash is " +"unavailable." msgstr "" -#: ../source/specifications/simple-repository-api.rst:572 +#: ../source/specifications/simple-repository-api.rst:280 #, fuzzy -msgid "Version + Format Selection" -msgstr "バージョン指定子" +msgid "Backwards Compatibility" +msgstr "ABI の互換性" -#: ../source/specifications/simple-repository-api.rst:574 +#: ../source/specifications/simple-repository-api.rst:282 msgid "" -"Now that there is multiple possible serializations, we need a mechanism to " -"allow clients to indicate what serialization formats they're able to " -"understand. In addition, it would be beneficial if any possible new major " -"version to the API can be added without disrupting existing clients " -"expecting the previous API version." +"If an anchor tag lacks the ``data-dist-info-metadata`` attribute, tools are " +"expected to revert to their current behaviour of downloading the " +"distribution to inspect the metadata." msgstr "" -#: ../source/specifications/simple-repository-api.rst:579 +#: ../source/specifications/simple-repository-api.rst:286 msgid "" -"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " -"Content Negotiation `_." +"Older tools not supporting the new ``data-dist-info-metadata`` attribute are " +"expected to ignore the attribute and maintain their current behaviour of " +"downloading the distribution to inspect the metadata. This is similar to how " +"prior ``data-`` attribute additions expect existing tools to operate." msgstr "" -#: ../source/specifications/simple-repository-api.rst:582 -msgid "" -"While this spec won't fully describe the entirety of server-driven content " -"negotiation, the flow is roughly:" +#: ../source/specifications/simple-repository-api.rst:295 +msgid "JSON-based Simple API for Python Package Indexes" msgstr "" -#: ../source/specifications/simple-repository-api.rst:585 +#: ../source/specifications/simple-repository-api.rst:297 msgid "" -"The client makes an HTTP request containing an ``Accept`` header listing all " -"of the version+format content types that they are able to understand." +"To enable response parsing with only the standard library, this spec " +"specifies that all responses (besides the files themselves, and the HTML " +"responses from :ref:`the base HTML API specification `) should be serialized using `JSON `_." msgstr "" -#: ../source/specifications/simple-repository-api.rst:587 +#: ../source/specifications/simple-repository-api.rst:302 msgid "" -"The server inspects that header, selects one of the listed content types, " -"then returns a response using that content type (treating the absence of an " -"``Accept`` header as ``Accept: */*``)." +"To enable zero configuration discovery and to minimize the amount of " +"additional HTTP requests, this spec extends :ref:`the base HTML API " +"specification ` such that all of the API " +"endpoints (other than the files themselves) will utilize HTTP content " +"negotiation to allow client and server to select the correct serialization " +"format to serve, i.e. either HTML or JSON." msgstr "" -#: ../source/specifications/simple-repository-api.rst:590 +#: ../source/specifications/simple-repository-api.rst:312 msgid "" -"If the server does not support any of the content types in the ``Accept`` " -"header then they are able to choose between 3 different options for how to " -"respond:" +"Versioning will adhere to :ref:`the API versioning specification ` format (``Major.Minor``), which has defined the " +"existing HTML responses to be ``1.0``. Since this spec does not introduce " +"new features into the API, rather it describes a different serialization " +"format for the existing features, this spec does not change the existing " +"``1.0`` version, and instead just describes how to serialize that into JSON." msgstr "" -#: ../source/specifications/simple-repository-api.rst:594 +#: ../source/specifications/simple-repository-api.rst:319 msgid "" -"Select a default content type other than what the client has requested and " -"return a response with that." +"Similar to :ref:`the API versioning specification `, the major version number **MUST** be incremented if any " +"changes to the new format would result in no longer being able to expect " +"existing clients to meaningfully understand the format." msgstr "" -#: ../source/specifications/simple-repository-api.rst:596 +#: ../source/specifications/simple-repository-api.rst:325 msgid "" -"Return a HTTP ``406 Not Acceptable`` response to indicate that none of the " -"requested content types were available, and the server was unable or " -"unwilling to select a default content type to respond with." +"Likewise, the minor version **MUST** be incremented if features are added or " +"removed from the format, but existing clients would be expected to continue " +"to meaningfully understand the format." msgstr "" -#: ../source/specifications/simple-repository-api.rst:599 +#: ../source/specifications/simple-repository-api.rst:329 msgid "" -"Return a HTTP ``300 Multiple Choices`` response that contains a list of all " -"of the possible responses that could have been chosen." +"Changes that would not result in existing clients being unable to " +"meaningfully understand the format and which do not represent features being " +"added or removed may occur without changing the version number." msgstr "" -#: ../source/specifications/simple-repository-api.rst:601 +#: ../source/specifications/simple-repository-api.rst:333 msgid "" -"The client interprets the response, handling the different types of " -"responses that the server may have responded with." +"This is intentionally vague, as this spec believes it is best left up to " +"future specs that make any changes to the API to investigate and decide " +"whether or not that change should increment the major or minor version." msgstr "" -#: ../source/specifications/simple-repository-api.rst:604 +#: ../source/specifications/simple-repository-api.rst:337 msgid "" -"This spec does not specify which choices the server makes in regards to " -"handling a content type that it isn't able to return, and clients **SHOULD** " -"be prepared to handle all of the possible responses in whatever way makes " -"the most sense for that client." +"Future versions of the API may add things that can only be represented in a " +"subset of the available serializations of that version. All serializations " +"version numbers, within a major version, **SHOULD** be kept in sync, but the " +"specifics of how a feature serializes into each format may differ, including " +"whether or not that feature is present at all." msgstr "" -#: ../source/specifications/simple-repository-api.rst:609 +#: ../source/specifications/simple-repository-api.rst:343 msgid "" -"However, as there is no standard format for how a ``300 Multiple Choices`` " -"response can be interpreted, this spec highly discourages servers from " -"utilizing that option, as clients will have no way to understand and select " -"a different content-type to request. In addition, it's unlikely that the " -"client *could* understand a different content type anyways, so at best this " -"response would likely just be treated the same as a ``406 Not Acceptable`` " -"error." +"It is the intent of this spec that the API should be thought of as URL " +"endpoints that return data, whose interpretation is defined by the version " +"of that data, and then serialized into the target serialization format." msgstr "" -#: ../source/specifications/simple-repository-api.rst:616 -msgid "" -"This spec **does** require that if the meta version ``latest`` is being " -"used, the server **MUST** respond with the content type for the actual " -"version that is contained in the response (i.e. A ``Accept: application/vnd." -"pypi.simple.latest+json`` request that returns a ``v1.x`` response should " -"have a ``Content-Type`` of ``application/vnd.pypi.simple.v1+json``)." -msgstr "" +#: ../source/specifications/simple-repository-api.rst:351 +#, fuzzy +msgid "JSON Serialization" +msgstr "正規化" -#: ../source/specifications/simple-repository-api.rst:623 +#: ../source/specifications/simple-repository-api.rst:353 msgid "" -"The ``Accept`` header is a comma separated list of content types that the " -"client understands and is able to process. It supports three different " -"formats for each content type that is being requested:" -msgstr "" - -#: ../source/specifications/simple-repository-api.rst:627 -msgid "``$type/$subtype``" -msgstr "" - -#: ../source/specifications/simple-repository-api.rst:628 -msgid "``$type/*``" -msgstr "" - -#: ../source/specifications/simple-repository-api.rst:629 -msgid "``*/*``" +"The URL structure from :ref:`the base HTML API specification ` still applies, as this spec only adds an additional " +"serialization format for the already existing API." msgstr "" -#: ../source/specifications/simple-repository-api.rst:631 +#: ../source/specifications/simple-repository-api.rst:357 msgid "" -"For the use of selecting a version+format, the most useful of these is " -"``$type/$subtype``, as that is the only way to actually specify the version " -"and format you want." +"The following constraints apply to all JSON serialized responses described " +"in this spec:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:635 +#: ../source/specifications/simple-repository-api.rst:360 msgid "" -"The order of the content types listed in the ``Accept`` header does not have " -"any specific meaning, and the server **SHOULD** consider all of them to be " -"equally valid to respond with. If a client wishes to specify that they " -"prefer a specific content type over another, they may use the ``Accept`` " -"header's `quality value `_ syntax." +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." msgstr "" -#: ../source/specifications/simple-repository-api.rst:642 -msgid "" -"This allows a client to specify a priority for a specific entry in their " -"``Accept`` header, by appending a ``;q=`` followed by a value between ``0`` " -"and ``1`` inclusive, with up to 3 decimal digits. When interpreting this " -"value, an entry with a higher quality has priority over an entry with a " -"lower quality, and any entry without a quality present will default to a " -"quality of ``1``." +#: ../source/specifications/simple-repository-api.rst:363 +msgid "" +"While JSON doesn't natively support an URL type, any value that represents " +"an URL in this API may be either absolute or relative as long as they point " +"to the correct location. If relative, they are relative to the current URL " +"as if it were HTML." msgstr "" -#: ../source/specifications/simple-repository-api.rst:648 +#: ../source/specifications/simple-repository-api.rst:368 msgid "" -"However, clients should keep in mind that a server is free to select **any** " -"of the content types they've asked for, regardless of their requested " -"priority, and it may even return a content type that they did **not** ask " -"for." +"Additional keys may be added to any dictionary objects in the API responses " +"and clients **MUST** ignore keys that they don't understand." msgstr "" -#: ../source/specifications/simple-repository-api.rst:652 +#: ../source/specifications/simple-repository-api.rst:371 msgid "" -"To aid clients in determining the content type of the response that they " -"have received from an API request, this spec requires that servers always " -"include a ``Content-Type`` header indicating the content type of the " -"response. This is technically a backwards incompatible change, however in " -"practice `pip has been enforcing this requirement `_ so the risks for actual breakages is low." +"All JSON responses will have a ``meta`` key, which contains information " +"related to the response itself, rather than the content of the response." msgstr "" -#: ../source/specifications/simple-repository-api.rst:659 -msgid "An example of how a client can operate would look like:" +#: ../source/specifications/simple-repository-api.rst:374 +msgid "" +"All JSON responses will have a ``meta.api-version`` key, which will be a " +"string that contains the :ref:`API versioning specification ` ``Major.Minor`` version number, with the same " +"fail/warn semantics as defined in :ref:`the API versioning specification " +"`." msgstr "" -#: ../source/specifications/simple-repository-api.rst:710 +#: ../source/specifications/simple-repository-api.rst:380 msgid "" -"If a client wishes to only support HTML or only support JSON, then they " -"would just remove the content types that they do not want from the " -"``Accept`` header, and turn receiving them into an error." +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." msgstr "" -#: ../source/specifications/simple-repository-api.rst:716 -msgid "Alternative Negotiation Mechanisms" -msgstr "" +#: ../source/specifications/simple-repository-api.rst:385 +#, fuzzy +msgid "Project List" +msgstr "プロジェクト" -#: ../source/specifications/simple-repository-api.rst:718 +#: ../source/specifications/simple-repository-api.rst:387 msgid "" -"While using HTTP's Content negotiation is considered the standard way for a " -"client and server to coordinate to ensure that the client is getting an HTTP " -"response that it is able to understand, there are situations where that " -"mechanism may not be sufficient. For those cases this spec has alternative " -"negotiation mechanisms that may *optionally* be used instead." +"The root URL ``/`` for this spec (which represents the base URL) will be a " +"JSON encoded dictionary which has a two keys:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:726 -msgid "URL Parameter" +#: ../source/specifications/simple-repository-api.rst:390 +msgid "" +"``projects``: An array where each entry is a dictionary with a single key, " +"``name``, which represents string of the project name." msgstr "" -#: ../source/specifications/simple-repository-api.rst:728 +#: ../source/specifications/simple-repository-api.rst:391 +#: ../source/specifications/simple-repository-api.rst:440 msgid "" -"Servers that implement the Simple API may choose to support an URL parameter " -"named ``format`` to allow the clients to request a specific version of the " -"URL." +"``meta``: The general response metadata as `described earlier `__." msgstr "" -#: ../source/specifications/simple-repository-api.rst:731 +#: ../source/specifications/simple-repository-api.rst:393 +#: ../source/specifications/simple-repository-api.rst:499 +#, fuzzy +msgid "As an example:" +msgstr "完全な例" + +#: ../source/specifications/simple-repository-api.rst:410 msgid "" -"The value of the ``format`` parameter should be **one** of the valid content " -"types. Passing multiple content types, wild cards, quality values, etc... is " -"**not** supported." +"The ``name`` field is the same as the one from :ref:`the base HTML API " +"specification `, which does not specify whether " +"it is the non-normalized display name or the normalized name. In practice " +"different implementations of these specs are choosing differently here, so " +"relying on it being either non-normalized or normalized is relying on an " +"implementation detail of the repository in question." msgstr "" -#: ../source/specifications/simple-repository-api.rst:735 +#: ../source/specifications/simple-repository-api.rst:420 msgid "" -"Supporting this parameter is optional, and clients **SHOULD NOT** rely on it " -"for interacting with the API. This negotiation mechanism is intended to " -"allow for easier human based exploration of the API within a browser, or to " -"allow documentation or notes to link to a specific version+format." +"While the ``projects`` key is an array, and thus is required to be in some " +"kind of an order, neither :ref:`the base HTML API specification ` nor this spec requires any specific ordering nor that " +"the ordering is consistent from one request to the next. Mentally this is " +"best thought of as a set, but both JSON and HTML lack the functionality to " +"have sets." msgstr "" -#: ../source/specifications/simple-repository-api.rst:740 +#: ../source/specifications/simple-repository-api.rst:429 +#, fuzzy +msgid "Project Detail" +msgstr "プロジェクト名" + +#: ../source/specifications/simple-repository-api.rst:431 msgid "" -"Servers that do not support this parameter may choose to return an error " -"when it is present, or they may simple ignore its presence." +"The format of this URL is ``//`` where the ```` is " +"replaced by the :ref:`the base HTML API specification ` normalized name for that project, so a project named \"Silly_Walk\" " +"would have a URL like ``/silly-walk/``." msgstr "" -#: ../source/specifications/simple-repository-api.rst:743 +#: ../source/specifications/simple-repository-api.rst:436 msgid "" -"When a server does implement this parameter, it **SHOULD** take precedence " -"over any values in the client's ``Accept`` header, and if the server does " -"not support the requested format, it may choose to fall back to the " -"``Accept`` header, or choose any of the error conditions that standard " -"server-driven content negotiation typically has (e.g. ``406 Not Available``, " -"``303 Multiple Choices``, or selecting a default type to return)." +"This URL must respond with a JSON encoded dictionary that has three keys:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:752 +#: ../source/specifications/simple-repository-api.rst:438 #, fuzzy -msgid "Endpoint Configuration" -msgstr "共通の設定" +msgid "``name``: The normalized name of the project." +msgstr "プロジェクトの名前。" -#: ../source/specifications/simple-repository-api.rst:754 +#: ../source/specifications/simple-repository-api.rst:439 msgid "" -"This option technically is not a special option at all, it is just a natural " -"consequence of using content negotiation and allowing servers to select " -"which of the available content types is their default." +"``files``: A list of dictionaries, each one representing an individual file." msgstr "" -#: ../source/specifications/simple-repository-api.rst:758 -msgid "" -"If a server is unwilling or unable to implement the server-driven content " -"negotiation, and would instead rather require users to explicitly configure " -"their client to select the version they want, then that is a supported " -"configuration." +#: ../source/specifications/simple-repository-api.rst:442 +msgid "Each individual file dictionary has the following keys:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:762 -msgid "" -"To enable this, a server should make multiple endpoints (for instance, ``/" -"simple/v1+html/`` and/or ``/simple/v1+json/``) for each version+format that " -"they wish to support. Under that endpoint, they can host a copy of their " -"repository that only supports one (or a subset) of the content-types. When a " -"client makes a request using the ``Accept`` header, the server can ignore it " -"and return the content type that corresponds to that endpoint." +#: ../source/specifications/simple-repository-api.rst:444 +msgid "``filename``: The filename that is being represented." msgstr "" -#: ../source/specifications/simple-repository-api.rst:769 +#: ../source/specifications/simple-repository-api.rst:445 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:446 +#, fuzzy msgid "" -"For clients that wish to require specific configuration, they can keep track " -"of which version+format a specific repository URL was configured for, and " -"when making a request to that server, emit an ``Accept`` header that *only* " -"includes the correct content type." +"``hashes``: A dictionary mapping a hash name to a hex encoded digest of the " +"file. Multiple hashes can be included, and it is up to the client to decide " +"what to do with multiple hashes (it may validate all of them or a subset of " +"them, or nothing at all). These hash names **SHOULD** always be normalized " +"to be lowercase." msgstr "" +"複数のハッシュ値を含めることが可能で、そのような複数のハッシュ値を使って何を" +"するか (すべてのハッシュ値を検証しても一部だけを検証しても構いませんし、何も" +"しなくても構いません) については利用する側次第です。" -#: ../source/specifications/simple-repository-api.rst:776 -msgid "TUF Support - PEP 458" +#: ../source/specifications/simple-repository-api.rst:451 +msgid "" +"The ``hashes`` dictionary **MUST** be present, even if no hashes are " +"available for the file, however it is **HIGHLY** recommended that at least " +"one secure, guaranteed-to-be-available hash is always included." msgstr "" -#: ../source/specifications/simple-repository-api.rst:778 +#: ../source/specifications/simple-repository-api.rst:455 +#, fuzzy msgid "" -":pep:`458` requires that all API responses are hashable and that they can be " -"uniquely identified by a path relative to the repository root. For a Simple " -"API repository, the target path is the Root of our API (e.g. ``/simple/`` on " -"PyPI). This creates challenges when accessing the API using a TUF client " -"instead of directly using a standard HTTP client, as the TUF client cannot " -"handle the fact that a target could have multiple different representations " -"that all hash differently." +"By default, any hash algorithm available via :py:mod:`hashlib` (specifically " +"any that can be passed to :py:func:`hashlib.new()` and do not require " +"additional parameters) can be used as a key for the hashes dictionary. At " +"least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"**SHOULD** always be included. At the time of this spec, ``sha256`` " +"specifically is recommended." msgstr "" +"``hash lib`` 経由で利用可能なハッシュアルゴリズム (とりわけ、 ``hashlib." +"new()`` に渡すことができて、かつ、追加的なパラメータを必要としないもの) はど" +"れでも、ハッシュ値を格納する辞書のキーとして用いることができます。 ``hashlib." +"algorithms_garanteed`` から安全なアルゴリズムを少なくともひとつ選択して (訳" +"注、ハッシュ値格納用辞書に) 含めるべきです。執筆時点では、 ``sha256`` が特に" +"推奨されています。" -#: ../source/specifications/simple-repository-api.rst:785 +#: ../source/specifications/simple-repository-api.rst:460 msgid "" -":pep:`458` does not specify what the target path should be for the Simple " -"API, but TUF requires that the target paths be \"file-like\", in other " -"words, a path like ``simple/PROJECT/`` is not acceptable, because it " -"technically points to a directory." +"``requires-python``: An **optional** key that exposes the :ref:`core-" +"metadata-requires-python` metadata field. Where this is present, installer " +"tools **SHOULD** ignore the download when installing to a Python version " +"that doesn't satisfy the requirement." msgstr "" -#: ../source/specifications/simple-repository-api.rst:790 +#: ../source/specifications/simple-repository-api.rst:466 msgid "" -"The saving grace is that the target path does not *have* to actually match " -"the URL being fetched from the Simple API, and it can just be a sigil that " -"the fetching code knows how to transform into the actual URL that needs to " -"be fetched. This same thing can hold true for other aspects of the actual " -"HTTP request, such as the ``Accept`` header." +"Unlike ``data-requires-python`` in :ref:`the base HTML API specification " +"`, the ``requires-python`` key does not require " +"any special escaping other than anything JSON does naturally." msgstr "" -#: ../source/specifications/simple-repository-api.rst:796 +#: ../source/specifications/simple-repository-api.rst:469 msgid "" -"Ultimately figuring out how to map a directory to a filename is out of scope " -"for this spec (but it would be in scope for :pep:`458`), and this spec " -"defers making a decision about how exactly to represent this inside of :pep:" -"`458` metadata." +"``dist-info-metadata``: An **optional** key that indicates that metadata for " +"this file is available, via the same location as specified in :ref:`the API " +"metadata file specification ` " +"(``{file_url}.metadata``). Where this is present, it **MUST** be either a " +"boolean to indicate if the file has an associated metadata file, or a " +"dictionary mapping hash names to a hex encoded digest of the metadata's hash." msgstr "" -#: ../source/specifications/simple-repository-api.rst:800 +#: ../source/specifications/simple-repository-api.rst:477 msgid "" -"However, it appears that the current WIP branch against pip that attempts to " -"implement :pep:`458` is using a target path like ``simple/PROJECT/index." -"html``. This could be modified to include the API version and serialization " -"format using something like ``simple/PROJECT/vnd.pypi.simple.vN.FORMAT``. So " -"the v1 HTML format would be ``simple/PROJECT/vnd.pypi.simple.v1.html`` and " -"the v1 JSON format would be ``simple/PROJECT/vnd.pypi.simple.v1.json``." +"When this is a dictionary of hashes instead of a boolean, then all the same " +"requirements and recommendations as the ``hashes`` key hold true for this " +"key as well." msgstr "" -#: ../source/specifications/simple-repository-api.rst:807 +#: ../source/specifications/simple-repository-api.rst:481 msgid "" -"In this case, since ``text/html`` is an alias to ``application/vnd.pypi." -"simple.v1+html`` when interacting through TUF, it likely will make the most " -"sense to normalize to the more explicit name." +"If this key is missing then the metadata file may or may not exist. If the " +"key value is truthy, then the metadata file is present, and if it is falsey " +"then it is not." msgstr "" -#: ../source/specifications/simple-repository-api.rst:811 +#: ../source/specifications/simple-repository-api.rst:485 msgid "" -"Likewise the ``latest`` metaversion should not be included in the targets, " -"only explicitly declared versions should be supported." +"It is recommended that servers make the hashes of the metadata file " +"available if possible." msgstr "" -#: ../source/specifications/simple-repository-api.rst:817 +#: ../source/specifications/simple-repository-api.rst:487 msgid "" -"This section is non-normative, and represents what the spec authors believe " -"to be the best default implementation decisions for something implementing " -"this spec, but it does **not** represent any sort of requirement to match " -"these decisions." +"``gpg-sig``: An **optional** key that acts a boolean to indicate if the file " +"has an associated GPG signature or not. The URL for the signature file " +"follows what is specified in :ref:`the base HTML API specification ` (``{file_url}.asc``). If this key does not exist, then " +"the signature may or may not exist." msgstr "" -#: ../source/specifications/simple-repository-api.rst:821 +#: ../source/specifications/simple-repository-api.rst:492 msgid "" -"These decisions have been chosen to maximize the number of requests that can " -"be moved onto the newest version of an API, while maintaining the greatest " -"amount of compatibility. In addition, they've also tried to make using the " -"API provide guardrails that attempt to push clients into making the best " -"choices it can." +"``yanked``: An **optional** key which may be either a boolean to indicate if " +"the file has been yanked, or a non empty, but otherwise arbitrary, string to " +"indicate that a file has been yanked with a specific reason. If the " +"``yanked`` key is present and is a truthy value, then it **SHOULD** be " +"interpreted as indicating that the file pointed to by the ``url`` field has " +"been \"Yanked\" as per :ref:`the API yank specification `." msgstr "" -#: ../source/specifications/simple-repository-api.rst:826 -msgid "It is recommended that servers:" +#: ../source/specifications/simple-repository-api.rst:529 +msgid "" +"While the ``files`` key is an array, and thus is required to be in some kind " +"of an order, neither :ref:`the base HTML API specification ` nor this spec requires any specific ordering nor that " +"the ordering is consistent from one request to the next. Mentally this is " +"best thought of as a set, but both JSON and HTML lack the functionality to " +"have sets." msgstr "" -#: ../source/specifications/simple-repository-api.rst:828 +#: ../source/specifications/simple-repository-api.rst:538 +#, fuzzy +msgid "Content-Types" +msgstr "内容" + +#: ../source/specifications/simple-repository-api.rst:540 msgid "" -"Support all 3 content types described in this spec, using server-driven " -"content negotiation, for as long as they reasonably can, or at least as long " -"as they're receiving non trivial traffic that uses the HTML responses." +"This spec proposes that all responses from the Simple API will have a " +"standard content type that describes what the response is (a Simple API " +"response), what version of the API it represents, and what serialization " +"format has been used." msgstr "" -#: ../source/specifications/simple-repository-api.rst:832 -msgid "" -"When encountering an ``Accept`` header that does not contain any content " -"types that it knows how to work with, the server should not ever return a " -"``300 Multiple Choice`` response, and instead return a ``406 Not " -"Acceptable`` response." +#: ../source/specifications/simple-repository-api.rst:544 +msgid "The structure of this content type will be:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:837 +#: ../source/specifications/simple-repository-api.rst:550 msgid "" -"However, if choosing to use the endpoint configuration, you should prefer to " -"return a ``200 OK`` response in the expected content type for that endpoint." +"Since only major versions should be disruptive to clients attempting to " +"understand one of these API responses, only the major version will be " +"included in the content type, and will be prefixed with a ``v`` to clarify " +"that it is a version number." msgstr "" -#: ../source/specifications/simple-repository-api.rst:840 -msgid "" -"When selecting an acceptable version, the server should choose the highest " -"version that the client supports, with the most expressive/featureful " -"serialization format, taking into account the specificity of the client " -"requests as well as any quality priority values they have expressed, and it " -"should only use the ``text/html`` content type as a last resort." +#: ../source/specifications/simple-repository-api.rst:555 +msgid "Which means that for the existing 1.0 API, the content types would be:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:846 -msgid "It is recommended that clients:" +#: ../source/specifications/simple-repository-api.rst:557 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" msgstr "" -#: ../source/specifications/simple-repository-api.rst:848 -msgid "" -"Support all 3 content types described in this spec, using server-driven " -"content negotiation, for as long as they reasonably can." +#: ../source/specifications/simple-repository-api.rst:558 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" msgstr "" -#: ../source/specifications/simple-repository-api.rst:851 +#: ../source/specifications/simple-repository-api.rst:560 msgid "" -"When constructing an ``Accept`` header, include all of the content types " -"that you support." +"In addition to the above, a special \"meta\" version is supported named " +"``latest``, whose purpose is to allow clients to request the absolute latest " +"version, without having to know ahead of time what that version is. It is " +"recommended however, that clients be explicit about what versions they " +"support." msgstr "" -#: ../source/specifications/simple-repository-api.rst:854 +#: ../source/specifications/simple-repository-api.rst:565 msgid "" -"You should generally *not* include a quality priority value for your content " -"types, unless you have implementation specific reasons that you want the " -"server to take into account (for example, if you're using the standard " -"library HTML parser and you're worried that there may be some kinds of HTML " -"responses that you're unable to parse in some edge cases)." +"To support existing clients which expect the existing :ref:`the base HTML " +"API specification ` API responses to use the " +"``text/html`` content type, this spec further defines ``text/html`` as an " +"alias for the ``application/vnd.pypi.simple.v1+html`` content type." msgstr "" -#: ../source/specifications/simple-repository-api.rst:860 +#: ../source/specifications/simple-repository-api.rst:572 +#, fuzzy +msgid "Version + Format Selection" +msgstr "バージョン指定子" + +#: ../source/specifications/simple-repository-api.rst:574 msgid "" -"The one exception to this recommendation is that it is recommended that you " -"*should* include a ``;q=0.01`` value on the legacy ``text/html`` content " -"type, unless it is the only content type that you are requesting." +"Now that there is multiple possible serializations, we need a mechanism to " +"allow clients to indicate what serialization formats they're able to " +"understand. In addition, it would be beneficial if any possible new major " +"version to the API can be added without disrupting existing clients " +"expecting the previous API version." msgstr "" -#: ../source/specifications/simple-repository-api.rst:864 +#: ../source/specifications/simple-repository-api.rst:579 msgid "" -"Explicitly select what versions they are looking for, rather than using the " -"``latest`` meta version during normal operation." +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." msgstr "" -#: ../source/specifications/simple-repository-api.rst:867 +#: ../source/specifications/simple-repository-api.rst:582 msgid "" -"Check the ``Content-Type`` of the response and ensure it matches something " -"that you were expecting." +"While this spec won't fully describe the entirety of server-driven content " +"negotiation, the flow is roughly:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:871 -msgid "Additional Fields for the Simple API for Package Indexes" +#: ../source/specifications/simple-repository-api.rst:585 +msgid "" +"The client makes an HTTP request containing an ``Accept`` header listing all " +"of the version+format content types that they are able to understand." msgstr "" -#: ../source/specifications/simple-repository-api.rst:873 +#: ../source/specifications/simple-repository-api.rst:587 msgid "" -"This specification defines version 1.1 of the simple repository API. For the " -"HTML version of the API, there is no change from version 1.0. For the JSON " -"version of the API, the following changes are made:" +"The server inspects that header, selects one of the listed content types, " +"then returns a response using that content type (treating the absence of an " +"``Accept`` header as ``Accept: */*``)." msgstr "" -#: ../source/specifications/simple-repository-api.rst:877 -msgid "The ``api-version`` must specify version 1.1 or later." +#: ../source/specifications/simple-repository-api.rst:590 +msgid "" +"If the server does not support any of the content types in the ``Accept`` " +"header then they are able to choose between 3 different options for how to " +"respond:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:878 -msgid "A new ``versions`` key is added at the top level." +#: ../source/specifications/simple-repository-api.rst:594 +msgid "" +"Select a default content type other than what the client has requested and " +"return a response with that." msgstr "" -#: ../source/specifications/simple-repository-api.rst:879 +#: ../source/specifications/simple-repository-api.rst:596 msgid "" -"Two new \"file information\" keys, ``size`` and ``upload-time``, are added " -"to the ``files`` data." +"Return a HTTP ``406 Not Acceptable`` response to indicate that none of the " +"requested content types were available, and the server was unable or " +"unwilling to select a default content type to respond with." msgstr "" -#: ../source/specifications/simple-repository-api.rst:881 +#: ../source/specifications/simple-repository-api.rst:599 msgid "" -"Keys (at any level) with a leading underscore are reserved as private for " -"index server use. No future standard will assign a meaning to any such key." +"Return a HTTP ``300 Multiple Choices`` response that contains a list of all " +"of the possible responses that could have been chosen." msgstr "" -#: ../source/specifications/simple-repository-api.rst:884 +#: ../source/specifications/simple-repository-api.rst:601 msgid "" -"The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key is " -"optional." +"The client interprets the response, handling the different types of " +"responses that the server may have responded with." msgstr "" -#: ../source/specifications/simple-repository-api.rst:890 +#: ../source/specifications/simple-repository-api.rst:604 msgid "" -"An additional key, ``versions`` MUST be present at the top level, in " -"addition to the keys ``name``, ``files`` and ``meta`` defined in :ref:`the " -"JSON API specification `. This key MUST contain " -"a list of version strings specifying all of the project versions uploaded " -"for this project. The value is logically a set, and as such may not contain " -"duplicates, and the order of the values is not significant." +"This spec does not specify which choices the server makes in regards to " +"handling a content type that it isn't able to return, and clients **SHOULD** " +"be prepared to handle all of the possible responses in whatever way makes " +"the most sense for that client." msgstr "" -#: ../source/specifications/simple-repository-api.rst:897 +#: ../source/specifications/simple-repository-api.rst:609 msgid "" -"All of the files listed in the ``files`` key MUST be associated with one of " -"the versions in the ``versions`` key. The ``versions`` key MAY contain " -"versions with no associated files (to represent versions with no files " -"uploaded, if the server has such a concept)." +"However, as there is no standard format for how a ``300 Multiple Choices`` " +"response can be interpreted, this spec highly discourages servers from " +"utilizing that option, as clients will have no way to understand and select " +"a different content-type to request. In addition, it's unlikely that the " +"client *could* understand a different content type anyways, so at best this " +"response would likely just be treated the same as a ``406 Not Acceptable`` " +"error." msgstr "" -#: ../source/specifications/simple-repository-api.rst:902 +#: ../source/specifications/simple-repository-api.rst:616 msgid "" -"Note that because servers may hold \"legacy\" data from before the adoption " -"of :ref:`the version specifiers specification (VSS) `, " -"version strings currently cannot be required to be valid VSS versions, and " -"therefore cannot be assumed to be orderable using the VSS rules. However, " -"servers SHOULD use normalised VSS versions where possible." +"This spec **does** require that if the meta version ``latest`` is being " +"used, the server **MUST** respond with the content type for the actual " +"version that is contained in the response (i.e. A ``Accept: application/vnd." +"pypi.simple.latest+json`` request that returns a ``v1.x`` response should " +"have a ``Content-Type`` of ``application/vnd.pypi.simple.v1+json``)." msgstr "" -#: ../source/specifications/simple-repository-api.rst:911 -#, fuzzy -msgid "Additional file information" -msgstr "補遺" - -#: ../source/specifications/simple-repository-api.rst:913 -msgid "Two new keys are added to the ``files`` key." +#: ../source/specifications/simple-repository-api.rst:623 +msgid "" +"The ``Accept`` header is a comma separated list of content types that the " +"client understands and is able to process. It supports three different " +"formats for each content type that is being requested:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:915 -msgid "" -"``size``: This field is mandatory. It MUST contain an integer which is the " -"file size in bytes." +#: ../source/specifications/simple-repository-api.rst:627 +msgid "``$type/$subtype``" msgstr "" -#: ../source/specifications/simple-repository-api.rst:917 -msgid "" -"``upload-time``: This field is optional. If present, it MUST contain a valid " -"ISO 8601 date/time string, in the format ``yyyy-mm-ddThh:mm:ss.ffffffZ``, " -"which represents the time the file was uploaded to the index. As indicated " -"by the ``Z`` suffix, the upload time MUST use the UTC timezone. The " -"fractional seconds part of the timestamp (the ``.ffffff`` part) is optional, " -"and if present may contain up to 6 digits of precision. If a server does not " -"record upload time information for a file, it MAY omit the ``upload-time`` " -"key." +#: ../source/specifications/simple-repository-api.rst:628 +msgid "``$type/*``" msgstr "" -#: ../source/specifications/simple-repository-api.rst:926 -msgid "Rename dist-info-metadata in the Simple API" +#: ../source/specifications/simple-repository-api.rst:629 +msgid "``*/*``" msgstr "" -#: ../source/specifications/simple-repository-api.rst:929 +#: ../source/specifications/simple-repository-api.rst:631 msgid "" -"The keywords \"**MUST**\", \"**MUST NOT**\", \"**REQUIRED**\", " -"\"**SHALL**\", \"**SHALL NOT**\", \"**SHOULD**\", \"**SHOULD NOT**\", " -"\"**RECOMMENDED**\", \"**MAY**\", and \"**OPTIONAL**\"\" in this document " -"are to be interpreted as described in :rfc:`RFC 2119 <2119>`." +"For the use of selecting a version+format, the most useful of these is " +"``$type/$subtype``, as that is the only way to actually specify the version " +"and format you want." msgstr "" -#: ../source/specifications/simple-repository-api.rst:936 -msgid "Servers" +#: ../source/specifications/simple-repository-api.rst:635 +msgid "" +"The order of the content types listed in the ``Accept`` header does not have " +"any specific meaning, and the server **SHOULD** consider all of them to be " +"equally valid to respond with. If a client wishes to specify that they " +"prefer a specific content type over another, they may use the ``Accept`` " +"header's `quality value `_ syntax." msgstr "" -#: ../source/specifications/simple-repository-api.rst:938 +#: ../source/specifications/simple-repository-api.rst:642 msgid "" -"The :ref:`the API metadata file specification ` metadata, when used in the HTML representation of the Simple " -"API, **MUST** be emitted using the attribute name ``data-core-metadata``, " -"with the supported values remaining the same." +"This allows a client to specify a priority for a specific entry in their " +"``Accept`` header, by appending a ``;q=`` followed by a value between ``0`` " +"and ``1`` inclusive, with up to 3 decimal digits. When interpreting this " +"value, an entry with a higher quality has priority over an entry with a " +"lower quality, and any entry without a quality present will default to a " +"quality of ``1``." msgstr "" -#: ../source/specifications/simple-repository-api.rst:944 +#: ../source/specifications/simple-repository-api.rst:648 msgid "" -"The :ref:`the API metadata file specification ` metadata, when used in the :ref:`the JSON API specification " -"` JSON representation of the Simple API, " -"**MUST** be emitted using the key ``core-metadata``, with the supported " -"values remaining the same." +"However, clients should keep in mind that a server is free to select **any** " +"of the content types they've asked for, regardless of their requested " +"priority, and it may even return a content type that they did **not** ask " +"for." msgstr "" -#: ../source/specifications/simple-repository-api.rst:950 +#: ../source/specifications/simple-repository-api.rst:652 msgid "" -"To support clients that used the previous key names, the HTML representation " -"**MAY** also be emitted using the ``data-dist-info-metadata``, and if it " -"does so it **MUST** match the value of ``data-core-metadata``." +"To aid clients in determining the content type of the response that they " +"have received from an API request, this spec requires that servers always " +"include a ``Content-Type`` header indicating the content type of the " +"response. This is technically a backwards incompatible change, however in " +"practice `pip has been enforcing this requirement `_ so the risks for actual breakages is low." msgstr "" -#: ../source/specifications/simple-repository-api.rst:959 -msgid "" -"Clients consuming any of the HTML representations of the Simple API **MUST** " -"read the :ref:`the API metadata file specification ` metadata from the key ``data-core-metadata`` if it is " -"present. They **MAY** optionally use the legacy ``data-dist-info-metadata`` " -"if it is present but ``data-core-metadata`` is not." +#: ../source/specifications/simple-repository-api.rst:659 +msgid "An example of how a client can operate would look like:" msgstr "" -#: ../source/specifications/simple-repository-api.rst:966 +#: ../source/specifications/simple-repository-api.rst:710 msgid "" -"Clients consuming the JSON representation of the Simple API **MUST** read " -"the :ref:`the API metadata file specification ` metadata from the key ``core-metadata`` if it is present. " -"They **MAY** optionally use the legacy ``dist-info-metadata`` key if it is " -"present but ``core-metadata`` is not." +"If a client wishes to only support HTML or only support JSON, then they " +"would just remove the content types that they do not want from the " +"``Accept`` header, and turn receiving them into an error." msgstr "" -#: ../source/specifications/simple-repository-api.rst:976 -msgid "September 2015: initial form of the HTML format, in :pep:`503`" +#: ../source/specifications/simple-repository-api.rst:716 +msgid "Alternative Negotiation Mechanisms" msgstr "" -#: ../source/specifications/simple-repository-api.rst:977 -msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +#: ../source/specifications/simple-repository-api.rst:718 +msgid "" +"While using HTTP's Content negotiation is considered the standard way for a " +"client and server to coordinate to ensure that the client is getting an HTTP " +"response that it is able to understand, there are situations where that " +"mechanism may not be sufficient. For those cases this spec has alternative " +"negotiation mechanisms that may *optionally* be used instead." msgstr "" -#: ../source/specifications/simple-repository-api.rst:978 -msgid "May 2019: \"yank\" support, in :pep:`592`" +#: ../source/specifications/simple-repository-api.rst:726 +msgid "URL Parameter" msgstr "" -#: ../source/specifications/simple-repository-api.rst:979 +#: ../source/specifications/simple-repository-api.rst:728 msgid "" -"July 2020: API versioning convention and metadata, and declaring the HTML " -"format as API v1, in :pep:`629`" +"Servers that implement the Simple API may choose to support an URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." msgstr "" -#: ../source/specifications/simple-repository-api.rst:981 +#: ../source/specifications/simple-repository-api.rst:731 msgid "" -"May 2021: providing package metadata independently from a package, in :pep:" -"`658`" +"The value of the ``format`` parameter should be **one** of the valid content " +"types. Passing multiple content types, wild cards, quality values, etc... is " +"**not** supported." msgstr "" -#: ../source/specifications/simple-repository-api.rst:983 +#: ../source/specifications/simple-repository-api.rst:735 msgid "" -"May 2022: initial form of the JSON format, with a mechanism for clients to " -"choose between them, and declaring both formats as API v1, in :pep:`691`" +"Supporting this parameter is optional, and clients **SHOULD NOT** rely on it " +"for interacting with the API. This negotiation mechanism is intended to " +"allow for easier human based exploration of the API within a browser, or to " +"allow documentation or notes to link to a specific version+format." msgstr "" -#: ../source/specifications/simple-repository-api.rst:985 +#: ../source/specifications/simple-repository-api.rst:740 msgid "" -"October 2022: project versions and file size and upload-time in the JSON " -"format, in :pep:`700`" +"Servers that do not support this parameter may choose to return an error " +"when it is present, or they may simple ignore its presence." msgstr "" -#: ../source/specifications/simple-repository-api.rst:987 +#: ../source/specifications/simple-repository-api.rst:743 msgid "" -"June 2023: renaming the field which provides package metadata independently " -"from a package, in :pep:`714`" +"When a server does implement this parameter, it **SHOULD** take precedence " +"over any values in the client's ``Accept`` header, and if the server does " +"not support the requested format, it may choose to fall back to the " +"``Accept`` header, or choose any of the error conditions that standard " +"server-driven content negotiation typically has (e.g. ``406 Not Available``, " +"``303 Multiple Choices``, or selecting a default type to return)." msgstr "" -#: ../source/specifications/source-distribution-format.rst:6 -msgid "Source distribution format" -msgstr "ソースコード配布物のフォーマット" +#: ../source/specifications/simple-repository-api.rst:752 +#, fuzzy +msgid "Endpoint Configuration" +msgstr "共通の設定" -#: ../source/specifications/source-distribution-format.rst:8 +#: ../source/specifications/simple-repository-api.rst:754 msgid "" -"The current standard format of source distribution format is identified by " -"the presence of a :file:`pyproject.toml` file in the distribution archive. " -"The layout of such a distribution was originally specified in :pep:`517` and " -"is formally documented here." +"This option technically is not a special option at all, it is just a natural " +"consequence of using content negotiation and allowing servers to select " +"which of the available content types is their default." msgstr "" -"ソースコード配布物のフォーマットに関する現在の標準フォーマットは、配布物の" -"アーカイブに :file:`pyproject.toml` ファイルが存在することで識別されます。そ" -"のような配布物のレイアウトは元々は :pep:`517` で指定され、ここに公式にドキュ" -"メント化されています。" -#: ../source/specifications/source-distribution-format.rst:13 +#: ../source/specifications/simple-repository-api.rst:758 msgid "" -"There is also the legacy source distribution format, implicitly defined by " -"the behaviour of ``distutils`` module in the standard library, when " -"executing :command:`setup.py sdist`. This document does not attempt to " -"standardise this format, except to note that if a legacy source distribution " -"contains a ``PKG-INFO`` file using metadata version 2.2 or later, then it " -"MUST follow the rules applicable to source distributions defined in the " -"metadata specification." +"If a server is unwilling or unable to implement the server-driven content " +"negotiation, and would instead rather require users to explicitly configure " +"their client to select the version they want, then that is a supported " +"configuration." msgstr "" -"これとは別に従来のソースコード配布物のフォーマットが存在しており、それは標準" -"ライブラリの ``distutils`` モジュールが :command:`setup.py sdist` の形で実行" -"される時の動作によって暗黙裡に定義されています。この説明文書では、この従来の" -"ソースコード配布物がバージョン 2.2 およびそれ以降のバージョンのメタデータを" -"使った ``PKG-INFO`` ファイルを含んでいる場合には、メタデータの仕様で定義され" -"たルールが該当のソースコード配布物にも適用されなければならないことを注記する" -"以外には、このフォーマットの標準化を試みることはしません。" -#: ../source/specifications/source-distribution-format.rst:21 -msgid "Source distributions are also known as *sdists* for short." -msgstr "ソースコード配布物は、短く *sdists* としても知られています。" +#: ../source/specifications/simple-repository-api.rst:762 +msgid "" +"To enable this, a server should make multiple endpoints (for instance, ``/" +"simple/v1+html/`` and/or ``/simple/v1+json/``) for each version+format that " +"they wish to support. Under that endpoint, they can host a copy of their " +"repository that only supports one (or a subset) of the content-types. When a " +"client makes a request using the ``Accept`` header, the server can ignore it " +"and return the content type that corresponds to that endpoint." +msgstr "" -#: ../source/specifications/source-distribution-format.rst:24 -msgid "Source trees" -msgstr "ソースコードツリー" +#: ../source/specifications/simple-repository-api.rst:769 +msgid "" +"For clients that wish to require specific configuration, they can keep track " +"of which version+format a specific repository URL was configured for, and " +"when making a request to that server, emit an ``Accept`` header that *only* " +"includes the correct content type." +msgstr "" -#: ../source/specifications/source-distribution-format.rst:26 +#: ../source/specifications/simple-repository-api.rst:776 +msgid "TUF Support - PEP 458" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:778 msgid "" -"A *source tree* is a collection of files and directories -- like a version " -"control system checkout -- which contains a :file:`pyproject.toml` file that " -"can be use to build a source distribution from the contained files and " -"directories. :pep:`517` and :pep:`518` specify what is required to meet the " -"definition of what :file:`pyproject.toml` must contain for something to be " -"deemed a source tree." +":pep:`458` requires that all API responses are hashable and that they can be " +"uniquely identified by a path relative to the repository root. For a Simple " +"API repository, the target path is the Root of our API (e.g. ``/simple/`` on " +"PyPI). This creates challenges when accessing the API using a TUF client " +"instead of directly using a standard HTTP client, as the TUF client cannot " +"handle the fact that a target could have multiple different representations " +"that all hash differently." msgstr "" -"*ソースツリー* は、 -- バージョン管理システムからのチェックアウトのような -- " -"ファイルとディレクトリの集合で、その中に書かれたファイルやディレクトリから" -"ソースコード配布物をビルドすることができるような :file:`pyproject.toml` ファ" -"イルを含んでいるものです。何かをソースコードツリーであると見做すために :file:" -"`pyproject.toml` ファイルが含んでいなければならないものが何であるかの定義に合" -"致するために要求されることは何であるかについては :pep:`517` と :pep:`518` が" -"指定しています。" -#: ../source/specifications/source-distribution-format.rst:34 -msgid "Source distribution file name" -msgstr "ソースコード配布物のファイル名" +#: ../source/specifications/simple-repository-api.rst:785 +msgid "" +":pep:`458` does not specify what the target path should be for the Simple " +"API, but TUF requires that the target paths be \"file-like\", in other " +"words, a path like ``simple/PROJECT/`` is not acceptable, because it " +"technically points to a directory." +msgstr "" -#: ../source/specifications/source-distribution-format.rst:36 +#: ../source/specifications/simple-repository-api.rst:790 msgid "" -"The file name of a sdist was standardised in :pep:`625`. The file name must " -"be in the form ``{name}-{version}.tar.gz``, where ``{name}`` is normalised " -"according to the same rules as for binary distributions (see :ref:`binary-" -"distribution-format`), and ``{version}`` is the canonicalized form of the " -"project version (see :ref:`version-specifiers`)." +"The saving grace is that the target path does not *have* to actually match " +"the URL being fetched from the Simple API, and it can just be a sigil that " +"the fetching code knows how to transform into the actual URL that needs to " +"be fetched. This same thing can hold true for other aspects of the actual " +"HTTP request, such as the ``Accept`` header." msgstr "" -"sdist のファイル名は、 :pep:`625` で標準化されています。ファイル名は " -"``{name}-{version}.tar.gz`` の形をしていなければならず、この中の ``{name}`` " -"はバイナリ配布物のファイル名に関するルールと同様のルールに従って正規化されて" -"いなければならず (:ref:`バイナリ配布物のフォーマット ` を見てください) 、かつ、 ``{version}`` はプロジェクトのバージョンの" -"形に正規化されていなければなりません (:ref:`バージョン指定子 ` を見てください) 。" -#: ../source/specifications/source-distribution-format.rst:42 +#: ../source/specifications/simple-repository-api.rst:796 msgid "" -"The name and version components of the filename MUST match the values stored " -"in the metadata contained in the file." +"Ultimately figuring out how to map a directory to a filename is out of scope " +"for this spec (but it would be in scope for :pep:`458`), and this spec " +"defers making a decision about how exactly to represent this inside of :pep:" +"`458` metadata." msgstr "" -"ファイル名の name と version の部分は、ファイル内のメタデータに保存されている" -"値に合致しなければなりません。" -#: ../source/specifications/source-distribution-format.rst:45 -#, fuzzy +#: ../source/specifications/simple-repository-api.rst:800 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 :" -"term:`build backend `." +"However, it appears that the current WIP branch against pip that attempts to " +"implement :pep:`458` is using a target path like ``simple/PROJECT/index." +"html``. This could be modified to include the API version and serialization " +"format using something like ``simple/PROJECT/vnd.pypi.simple.vN.FORMAT``. So " +"the v1 HTML format would be ``simple/PROJECT/vnd.pypi.simple.v1.html`` and " +"the v1 JSON format would be ``simple/PROJECT/vnd.pypi.simple.v1.json``." msgstr "" -"ソースコード配布物を生成するソースコードは、この仕様に合致した名前をファイル" -"に与えなければなりません。これは、ビルドバックエンドの ``build_sdist`` フック" -"にも当てはまります。" -#: ../source/specifications/source-distribution-format.rst:49 +#: ../source/specifications/simple-repository-api.rst:807 msgid "" -"Code that processes source distribution files MAY recognise source " -"distribution files by the ``.tar.gz`` suffix and the presence of precisely " -"*one* hyphen in the filename. Code that does this may then use the " -"distribution name and version from the filename without further verification." +"In this case, since ``text/html`` is an alias to ``application/vnd.pypi." +"simple.v1+html`` when interacting through TUF, it likely will make the most " +"sense to normalize to the more explicit name." msgstr "" -"ソースコード配布物を生成するソースコードは、 ``.tar.gz`` 拡張子がついていて" -"ファイル名の中に正確に *ひとつ* のハイフンが存在していることを以て、ソース" -"コード配布物のファイルであると認識しても構いません。これを行うソースコード" -"は、この場合には、ファイル名から得た配布物の名前とバージョンをそれ以上の検証" -"をせずに使用しても構いません。" - -#: ../source/specifications/source-distribution-format.rst:55 -msgid "Source distribution file format" -msgstr "ソースコード配布物のファイルフォーマット" -#: ../source/specifications/source-distribution-format.rst:57 -#, fuzzy +#: ../source/specifications/simple-repository-api.rst:811 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:`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." +"Likewise the ``latest`` metaversion should not be included in the targets, " +"only explicitly declared versions should be supported." 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 のメタデータ仕様を満足するものでなければ" -"なりません。" -#: ../source/specifications/source-distribution-format.rst:65 +#: ../source/specifications/simple-repository-api.rst:817 msgid "" -"No other content of a sdist is required or defined. Build systems can store " -"whatever information they need in the sdist to build the project." +"This section is non-normative, and represents what the spec authors believe " +"to be the best default implementation decisions for something implementing " +"this spec, but it does **not** represent any sort of requirement to match " +"these decisions." msgstr "" -"sdist の他の内容については必須でもなく定義もされていません。ビルドシステム" -"は、プロジェクトをビルドするのに必要なものであればどんな情報でも sdist 内に保" -"存しておくことができます。" -#: ../source/specifications/source-distribution-format.rst:68 +#: ../source/specifications/simple-repository-api.rst:821 msgid "" -"The tarball should use the modern POSIX.1-2001 pax tar format, which " -"specifies UTF-8 based file names. In particular, source distribution files " -"must be readable using the standard library tarfile module with the open " -"flag 'r:gz'." +"These decisions have been chosen to maximize the number of requests that can " +"be moved onto the newest version of an API, while maintaining the greatest " +"amount of compatibility. In addition, they've also tried to make using the " +"API provide guardrails that attempt to push clients into making the best " +"choices it can." msgstr "" -"tar ボールでは、ファイル名に UTF-8 を使える近代的な POSIX.1-2001 pax tar " -"フォーマットを使用するべきです。とりわけ、ソースコード配布物のファイル群は、" -"標準ライブラリの tarfile モジュールに open flag 'r:gz' を与えることで読み込め" -"るものでなければなりません。" -#: ../source/specifications/source-distribution-format.rst:76 -msgid "Source distribution archive features" -msgstr "ソースコード配布物アーカイブの機能" +#: ../source/specifications/simple-repository-api.rst:826 +msgid "It is recommended that servers:" +msgstr "" -#: ../source/specifications/source-distribution-format.rst:78 +#: ../source/specifications/simple-repository-api.rst:828 msgid "" -"Because extracting tar files as-is is dangerous, and the results are " -"platform-specific, archive features of source distributions are limited." +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can, or at least as long " +"as they're receiving non trivial traffic that uses the HTML responses." msgstr "" -"tar ファイルをそのまま展開することは危険を伴うため、また、展開結果がプラット" -"フォーム依存になるため、ソースコード配布物アーカイブの機能は制限されていま" -"す。" -#: ../source/specifications/source-distribution-format.rst:82 -msgid "Unpacking with the data filter" -msgstr "データフィルタしながらアンパックする" +#: ../source/specifications/simple-repository-api.rst:832 +msgid "" +"When encountering an ``Accept`` header that does not contain any content " +"types that it knows how to work with, the server should not ever return a " +"``300 Multiple Choice`` response, and instead return a ``406 Not " +"Acceptable`` response." +msgstr "" -#: ../source/specifications/source-distribution-format.rst:84 +#: ../source/specifications/simple-repository-api.rst:837 msgid "" -"When extracting a source distribution, tools MUST either use :py:func:" -"`tarfile.data_filter` (e.g. :py:meth:`TarFile.extractall(..., filter='data') " -"`), OR follow the *Unpacking without the data " -"filter* section below." +"However, if choosing to use the endpoint configuration, you should prefer to " +"return a ``200 OK`` response in the expected content type for that endpoint." msgstr "" -"ソースコード配布物を展開する時には、ツール類は、 :py:func:`tarfile." -"data_filter` (例えば :py:meth:`TarFile.extractall(..., filter='data') " -"`) か、あるいは、後述する *データフィルタなしでア" -"ンパックする* 節に従うか、いずれかを行わな" -"ければなりません。" -#: ../source/specifications/source-distribution-format.rst:88 +#: ../source/specifications/simple-repository-api.rst:840 msgid "" -"As an exception, on Python interpreters without :py:func:`hasattr(tarfile, " -"'data_filter') ` (:pep:`706`), tools that normally use " -"that filter (directly on indirectly) MAY warn the user and ignore this " -"specification. The trade-off between usability (e.g. fully trusting the " -"archive) and security (e.g. refusing to unpack) is left up to the tool in " -"this case." +"When selecting an acceptable version, the server should choose the highest " +"version that the client supports, with the most expressive/featureful " +"serialization format, taking into account the specificity of the client " +"requests as well as any quality priority values they have expressed, and it " +"should only use the ``text/html`` content type as a last resort." msgstr "" -"例外として、 :py:func:`hasattr(tarfile, 'data_filter') ` (:pep:`706`) を持たない Python インタープリタ上では、通常ならそ" -"のようなフィルタを使うはずのツール類はユーザに対して警告した上でこの仕様を無" -"視しても構いません。利便性 (例えばアーカイブを完全に信頼すること) とセキュリ" -"ティ (例えばアンパックすることを拒否すること) の間のトレードオフは、この場合" -"にはツールに委ねられています。" -#: ../source/specifications/source-distribution-format.rst:96 -msgid "Unpacking without the data filter" -msgstr "データフィルタなしでアンパックする" +#: ../source/specifications/simple-repository-api.rst:846 +msgid "It is recommended that clients:" +msgstr "" -#: ../source/specifications/source-distribution-format.rst:98 +#: ../source/specifications/simple-repository-api.rst:848 msgid "" -"Tools that do not use the ``data`` filter directly (e.g. for backwards " -"compatibility, allowing additional features, or not using Python) MUST " -"follow this section. (At the time of this writing, the ``data`` filter also " -"follows this section, but it may get out of sync in the future.)" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." msgstr "" -"(例えば、後方互換性のためであったり、追加的な機能を許容するためであったり、あ" -"るいは Python を使わない場合であったりで) ``データ `` フィルタを直接に" -"は使わないツール類は、この節の内容に従わなければなりません。(執筆時点では、 " -"``データ `` フィルタもこの節の内容に従うものになっていますが、将来には" -"この同期が外れるかもしれません。)" -#: ../source/specifications/source-distribution-format.rst:104 +#: ../source/specifications/simple-repository-api.rst:851 msgid "" -"The following files are invalid in an *sdist* archive. Upon encountering " -"such an entry, tools SHOULD notify the user, MUST NOT unpack the entry, and " -"MAY abort with a failure:" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." msgstr "" -"以下に述べるファイル群は、 *sdist* アーカイブの中に置くには不適格です。そのよ" -"うなエントリに遭遇した場合には、ツール類はユーザに通知するべきであり、そのエ" -"ントリをアンパックしてはならず、そして、エラー (failure) とともに処理を中断し" -"ても構いません:" - -#: ../source/specifications/source-distribution-format.rst:108 -msgid "Files that would be placed outside the destination directory." -msgstr "宛先となるディレクトリの外側に置かれるファイル群。" -#: ../source/specifications/source-distribution-format.rst:109 -msgid "Links (symbolic or hard) pointing outside the destination directory." +#: ../source/specifications/simple-repository-api.rst:854 +msgid "" +"You should generally *not* include a quality priority value for your content " +"types, unless you have implementation specific reasons that you want the " +"server to take into account (for example, if you're using the standard " +"library HTML parser and you're worried that there may be some kinds of HTML " +"responses that you're unable to parse in some edge cases)." msgstr "" -"宛先となるディレクトリの外側を指し示すリンク (シンボリックでもハードでも)。" - -#: ../source/specifications/source-distribution-format.rst:110 -msgid "Device files (including pipes)." -msgstr "デバイスファイル (パイプを含む)。" -#: ../source/specifications/source-distribution-format.rst:112 +#: ../source/specifications/simple-repository-api.rst:860 msgid "" -"The following are also invalid. Tools MAY treat them as above, but are NOT " -"REQUIRED to do so:" +"The one exception to this recommendation is that it is recommended that you " +"*should* include a ``;q=0.01`` value on the legacy ``text/html`` content " +"type, unless it is the only content type that you are requesting." msgstr "" -"以下に示すものもまた、不適格です。ツール類はこれらを上記のように扱っても構い" -"ませんが、そうすることを要求されているわけではありません:" - -#: ../source/specifications/source-distribution-format.rst:115 -msgid "Files with a ``..`` component in the filename or link target." -msgstr "ファイル名の一部に ``..`` を含むファイルまたはリンクのターゲット。" -#: ../source/specifications/source-distribution-format.rst:116 -msgid "Links pointing to a file that is not part of the archive." -msgstr "当該アーカイブの一部ではないファイルを指し示すリンク。" +#: ../source/specifications/simple-repository-api.rst:864 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" -#: ../source/specifications/source-distribution-format.rst:118 +#: ../source/specifications/simple-repository-api.rst:867 msgid "" -"Tools MAY unpack links (symbolic or hard) as regular files, using content " -"from the archive." +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." msgstr "" -"ツール類は、アーカイブから得た内容を使って、リンク類 (シンボリックまたはハー" -"ド) をアンパックしても構いません。" -#: ../source/specifications/source-distribution-format.rst:121 -msgid "When extracting *sdist* archives:" -msgstr "*sdist* アーカイブを展開する時:" +#: ../source/specifications/simple-repository-api.rst:871 +msgid "Additional Fields for the Simple API for Package Indexes" +msgstr "" -#: ../source/specifications/source-distribution-format.rst:123 +#: ../source/specifications/simple-repository-api.rst:873 msgid "" -"Leading slashes in file names MUST be dropped. (This is nowadays standard " -"behaviour for ``tar`` unpacking.)" +"This specification defines version 1.1 of the simple repository API. For the " +"HTML version of the API, there is no change from version 1.0. For the JSON " +"version of the API, the following changes are made:" msgstr "" -"ファイル名の先頭のスラッシュは、必ず削除しなければなりません。 (これは、 " -"``tar`` を展開する時の今日的な標準的な振る舞いです。)" -#: ../source/specifications/source-distribution-format.rst:125 -msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +#: ../source/specifications/simple-repository-api.rst:877 +msgid "The ``api-version`` must specify version 1.1 or later." msgstr "" -"``モード `` (UNIXでのパーミッション) の各ビットについて、ツール類は以下" -"のうちのいずれかをしなければなりません:" -#: ../source/specifications/source-distribution-format.rst:127 -msgid "use the platform's default for a new file/directory (respectively)," +#: ../source/specifications/simple-repository-api.rst:878 +msgid "A new ``versions`` key is added at the top level." msgstr "" -"プラットフォームの既定値を新しく作るファイル/ディレクトリに (それぞれ) 適用す" -"るか、" -#: ../source/specifications/source-distribution-format.rst:128 -msgid "set the bit according to the archive, or" -msgstr "アーカイブにおける (パーミッション) ビットに従って設定するか、または、" +#: ../source/specifications/simple-repository-api.rst:879 +msgid "" +"Two new \"file information\" keys, ``size`` and ``upload-time``, are added " +"to the ``files`` data." +msgstr "" -#: ../source/specifications/source-distribution-format.rst:129 +#: ../source/specifications/simple-repository-api.rst:881 msgid "" -"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " -"``rwxr-xr-x`` (``0o755``) for executable files and directories." +"Keys (at any level) with a leading underscore are reserved as private for " +"index server use. No future standard will assign a meaning to any such key." msgstr "" -"非実行ファイルには ``rw-r--r--`` (``0o644``) の (パーミッション) ビットを設定" -"し、実行ファイルとディレクトリには ``rwxr-xr-x`` (``0o755``) を設定する。" -#: ../source/specifications/source-distribution-format.rst:132 -msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +#: ../source/specifications/simple-repository-api.rst:884 +msgid "" +"The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key is " +"optional." msgstr "" -"特殊な ``モード `` ビット (setups, setgid, sticky) については、削除 (ク" -"リア) しなければなりません。" -#: ../source/specifications/source-distribution-format.rst:133 -msgid "It is RECOMMENDED to preserve the user *executable* bit." +#: ../source/specifications/simple-repository-api.rst:890 +msgid "" +"An additional key, ``versions`` MUST be present at the top level, in " +"addition to the keys ``name``, ``files`` and ``meta`` defined in :ref:`the " +"JSON API specification `. This key MUST contain " +"a list of version strings specifying all of the project versions uploaded " +"for this project. The value is logically a set, and as such may not contain " +"duplicates, and the order of the values is not significant." msgstr "" -"ユーザ (多分オーナのこと) *実行* ビットについては、そのまま保存することが推奨" -"されています。" - -#: ../source/specifications/source-distribution-format.rst:137 -msgid "Further hints" -msgstr "さらなるヒント" -#: ../source/specifications/source-distribution-format.rst:139 +#: ../source/specifications/simple-repository-api.rst:897 msgid "" -"Tool authors are encouraged to consider how *hints for further verification* " -"in ``tarfile`` documentation apply to their tool." +"All of the files listed in the ``files`` key MUST be associated with one of " +"the versions in the ``versions`` key. The ``versions`` key MAY contain " +"versions with no associated files (to represent versions with no files " +"uploaded, if the server has such a concept)." msgstr "" -"ツールの作成者は、自分たちのツールに適用する ``tarfile`` 説明文書の中に、*さ" -"らなる検証を行うためのヒント集* を含めることを検討するように推奨されていま" -"す。" -#: ../source/specifications/source-distribution-format.rst:146 +#: ../source/specifications/simple-repository-api.rst:902 msgid "" -"November 2020: The original version of this specification was approved " -"through :pep:`643`." +"Note that because servers may hold \"legacy\" data from before the adoption " +"of :ref:`the version specifiers specification (VSS) `, " +"version strings currently cannot be required to be valid VSS versions, and " +"therefore cannot be assumed to be orderable using the VSS rules. However, " +"servers SHOULD use normalised VSS versions where possible." msgstr "" -#: ../source/specifications/source-distribution-format.rst:148 +#: ../source/specifications/simple-repository-api.rst:911 #, fuzzy -msgid "July 2021: Defined what a source tree is." -msgstr "2021-07: ソースコードツリーとは何であるかを定義" +msgid "Additional file information" +msgstr "補遺" -#: ../source/specifications/source-distribution-format.rst:149 -#, fuzzy -msgid "" -"September 2022: The filename of a source distribution was standardized " -"through :pep:`625`." -msgstr "2022-09: ソースコード配布物のファイル名について標準化 (:pep:`625`)" +#: ../source/specifications/simple-repository-api.rst:913 +msgid "Two new keys are added to the ``files`` key." +msgstr "" -#: ../source/specifications/source-distribution-format.rst:151 -#, fuzzy +#: ../source/specifications/simple-repository-api.rst:915 msgid "" -"August 2023: Source distribution archive features were standardized through :" -"pep:`721`." +"``size``: This field is mandatory. It MUST contain an integer which is the " +"file size in bytes." msgstr "" -"2023-08: ソースコード配布物のアーカイブの機能について標準化 (: pep:`721`)" - -#: ../source/specifications/version-specifiers.rst:7 -#: ../source/specifications/version-specifiers.rst:780 -msgid "Version specifiers" -msgstr "バージョン指定子" -#: ../source/specifications/version-specifiers.rst:10 +#: ../source/specifications/simple-repository-api.rst:917 msgid "" -"This specification describes a scheme for identifying versions of Python " -"software distributions, and declaring dependencies on particular versions." +"``upload-time``: This field is optional. If present, it MUST contain a valid " +"ISO 8601 date/time string, in the format ``yyyy-mm-ddThh:mm:ss.ffffffZ``, " +"which represents the time the file was uploaded to the index. As indicated " +"by the ``Z`` suffix, the upload time MUST use the UTC timezone. The " +"fractional seconds part of the timestamp (the ``.ffffff`` part) is optional, " +"and if present may contain up to 6 digits of precision. If a server does not " +"record upload time information for a file, it MAY omit the ``upload-time`` " +"key." msgstr "" -#: ../source/specifications/version-specifiers.rst:15 -#, fuzzy -msgid "Definitions" -msgstr "仕様型文書" +#: ../source/specifications/simple-repository-api.rst:926 +msgid "Rename dist-info-metadata in the Simple API" +msgstr "" -#: ../source/specifications/version-specifiers.rst:17 +#: ../source/specifications/simple-repository-api.rst:929 msgid "" -"The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " -"NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " -"\"OPTIONAL\" in this document are to be interpreted as described in :rfc:" -"`2119`." +"The keywords \"**MUST**\", \"**MUST NOT**\", \"**REQUIRED**\", " +"\"**SHALL**\", \"**SHALL NOT**\", \"**SHOULD**\", \"**SHOULD NOT**\", " +"\"**RECOMMENDED**\", \"**MAY**\", and \"**OPTIONAL**\"\" in this document " +"are to be interpreted as described in :rfc:`RFC 2119 <2119>`." msgstr "" -#: ../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 " -"invoked by integration tools in order to build software distributed as " -"sdists rather than prebuilt binary archives." +#: ../source/specifications/simple-repository-api.rst:936 +msgid "Servers" msgstr "" -#: ../source/specifications/version-specifiers.rst:26 +#: ../source/specifications/simple-repository-api.rst:938 msgid "" -"\"Index servers\" are active distribution registries which publish version " -"and dependency metadata and place constraints on the permitted metadata." +"The :ref:`the API metadata file specification ` metadata, when used in the HTML representation of the Simple " +"API, **MUST** be emitted using the attribute name ``data-core-metadata``, " +"with the supported values remaining the same." msgstr "" -#: ../source/specifications/version-specifiers.rst:29 +#: ../source/specifications/simple-repository-api.rst:944 msgid "" -"\"Publication tools\" are automated tools intended to run on development " -"systems and upload source and binary distribution archives to index servers." +"The :ref:`the API metadata file specification ` metadata, when used in the :ref:`the JSON API specification " +"` JSON representation of the Simple API, " +"**MUST** be emitted using the key ``core-metadata``, with the supported " +"values remaining the same." msgstr "" -#: ../source/specifications/version-specifiers.rst:32 +#: ../source/specifications/simple-repository-api.rst:950 msgid "" -"\"Installation tools\" are integration tools specifically intended to run on " -"deployment targets, consuming source and binary distribution archives from " -"an index server or other designated location and deploying them to the " -"target system." +"To support clients that used the previous key names, the HTML representation " +"**MAY** also be emitted using the ``data-dist-info-metadata``, and if it " +"does so it **MUST** match the value of ``data-core-metadata``." msgstr "" -#: ../source/specifications/version-specifiers.rst:37 +#: ../source/specifications/simple-repository-api.rst:959 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." +"Clients consuming any of the HTML representations of the Simple API **MUST** " +"read the :ref:`the API metadata file specification ` metadata from the key ``data-core-metadata`` if it is " +"present. They **MAY** optionally use the legacy ``data-dist-info-metadata`` " +"if it is present but ``data-core-metadata`` is not." msgstr "" -#: ../source/specifications/version-specifiers.rst:43 -#, fuzzy -msgid "Version scheme" -msgstr "バージョン指定子" - -#: ../source/specifications/version-specifiers.rst:45 +#: ../source/specifications/simple-repository-api.rst:966 msgid "" -"Distributions are identified by a public version identifier which supports " -"all defined version comparison operations" +"Clients consuming the JSON representation of the Simple API **MUST** read " +"the :ref:`the API metadata file specification ` metadata from the key ``core-metadata`` if it is present. " +"They **MAY** optionally use the legacy ``dist-info-metadata`` key if it is " +"present but ``core-metadata`` is not." msgstr "" -#: ../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 " -"constraints on the version of dependencies needed in order to build or run " -"the software." +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 -#, fuzzy -msgid "Public version identifiers" -msgstr "ローカルのバージョン指定子" +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" -#: ../source/specifications/version-specifiers.rst:59 -msgid "" -"The canonical public version identifiers MUST comply with the following " -"scheme::" +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/simple-repository-api.rst:979 msgid "" -"Public version identifiers MUST NOT include leading or trailing whitespace." +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" msgstr "" -#: ../source/specifications/version-specifiers.rst:66 -msgid "Public version identifiers MUST be unique within a given distribution." +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, in :pep:" +"`658`" msgstr "" -#: ../source/specifications/version-specifiers.rst:68 +#: ../source/specifications/simple-repository-api.rst:983 msgid "" -"Installation tools SHOULD ignore any public versions which do not comply " -"with this scheme but MUST also include the normalizations specified below. " -"Installation tools MAY warn the user when non-compliant or ambiguous " -"versions are detected." +"May 2022: initial form of the JSON format, with a mechanism for clients to " +"choose between them, and declaring both formats as API v1, in :pep:`691`" msgstr "" -#: ../source/specifications/version-specifiers.rst:73 +#: ../source/specifications/simple-repository-api.rst:985 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 " -"permissive regular expression accepting inputs that may require subsequent " -"normalization." +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 -msgid "Public version identifiers are separated into up to five segments:" +#: ../source/specifications/simple-repository-api.rst:987 +msgid "" +"June 2023: renaming the field which provides package metadata independently " +"from a package, in :pep:`714`" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 -msgid "Epoch segment: ``N!``" -msgstr "" +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "ソースコード配布物のフォーマット" -#: ../source/specifications/version-specifiers.rst:81 -msgid "Release segment: ``N(.N)*``" +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard format of source distribution format is identified by " +"the presence of a :file:`pyproject.toml` file in the distribution archive. " +"The layout of such a distribution was originally specified in :pep:`517` and " +"is formally documented here." msgstr "" +"ソースコード配布物のフォーマットに関する現在の標準フォーマットは、配布物の" +"アーカイブに :file:`pyproject.toml` ファイルが存在することで識別されます。そ" +"のような配布物のレイアウトは元々は :pep:`517` で指定され、ここに公式にドキュ" +"メント化されています。" -#: ../source/specifications/version-specifiers.rst:82 -msgid "Pre-release segment: ``{a|b|rc}N``" +#: ../source/specifications/source-distribution-format.rst:13 +msgid "" +"There is also the legacy source distribution format, implicitly defined by " +"the behaviour of ``distutils`` module in the standard library, when " +"executing :command:`setup.py sdist`. This document does not attempt to " +"standardise this format, except to note that if a legacy source distribution " +"contains a ``PKG-INFO`` file using metadata version 2.2 or later, then it " +"MUST follow the rules applicable to source distributions defined in the " +"metadata specification." msgstr "" +"これとは別に従来のソースコード配布物のフォーマットが存在しており、それは標準" +"ライブラリの ``distutils`` モジュールが :command:`setup.py sdist` の形で実行" +"される時の動作によって暗黙裡に定義されています。この説明文書では、この従来の" +"ソースコード配布物がバージョン 2.2 およびそれ以降のバージョンのメタデータを" +"使った ``PKG-INFO`` ファイルを含んでいる場合には、メタデータの仕様で定義され" +"たルールが該当のソースコード配布物にも適用されなければならないことを注記する" +"以外には、このフォーマットの標準化を試みることはしません。" -#: ../source/specifications/version-specifiers.rst:83 -msgid "Post-release segment: ``.postN``" -msgstr "" +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "ソースコード配布物は、短く *sdists* としても知られています。" -#: ../source/specifications/version-specifiers.rst:84 -msgid "Development release segment: ``.devN``" -msgstr "" +#: ../source/specifications/source-distribution-format.rst:24 +msgid "Source trees" +msgstr "ソースコードツリー" -#: ../source/specifications/version-specifiers.rst:86 +#: ../source/specifications/source-distribution-format.rst:26 msgid "" -"Any given release will be a \"final release\", \"pre-release\", \"post-" -"release\" or \"developmental release\" as defined in the following sections." +"A *source tree* is a collection of files and directories -- like a version " +"control system checkout -- which contains a :file:`pyproject.toml` file that " +"can be use to build a source distribution from the contained files and " +"directories. :pep:`517` and :pep:`518` specify what is required to meet the " +"definition of what :file:`pyproject.toml` must contain for something to be " +"deemed a source tree." msgstr "" +"*ソースツリー* は、 -- バージョン管理システムからのチェックアウトのような -- " +"ファイルとディレクトリの集合で、その中に書かれたファイルやディレクトリから" +"ソースコード配布物をビルドすることができるような :file:`pyproject.toml` ファ" +"イルを含んでいるものです。何かをソースコードツリーであると見做すために :file:" +"`pyproject.toml` ファイルが含んでいなければならないものが何であるかの定義に合" +"致するために要求されることは何であるかについては :pep:`517` と :pep:`518` が" +"指定しています。" -#: ../source/specifications/version-specifiers.rst:89 -msgid "" -"All numeric components MUST be non-negative integers represented as " -"sequences of ASCII digits." -msgstr "" +#: ../source/specifications/source-distribution-format.rst:34 +msgid "Source distribution file name" +msgstr "ソースコード配布物のファイル名" -#: ../source/specifications/version-specifiers.rst:92 +#: ../source/specifications/source-distribution-format.rst:36 msgid "" -"All numeric components MUST be interpreted and ordered according to their " -"numeric value, not as text strings." +"The file name of a sdist was standardised in :pep:`625`. The file name must " +"be in the form ``{name}-{version}.tar.gz``, where ``{name}`` is normalised " +"according to the same rules as for binary distributions (see :ref:`binary-" +"distribution-format`), and ``{version}`` is the canonicalized form of the " +"project version (see :ref:`version-specifiers`)." msgstr "" +"sdist のファイル名は、 :pep:`625` で標準化されています。ファイル名は " +"``{name}-{version}.tar.gz`` の形をしていなければならず、この中の ``{name}`` " +"はバイナリ配布物のファイル名に関するルールと同様のルールに従って正規化されて" +"いなければならず (:ref:`バイナリ配布物のフォーマット ` を見てください) 、かつ、 ``{version}`` はプロジェクトのバージョンの" +"形に正規化されていなければなりません (:ref:`バージョン指定子 ` を見てください) 。" -#: ../source/specifications/version-specifiers.rst:95 +#: ../source/specifications/source-distribution-format.rst:42 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." +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." msgstr "" +"ファイル名の name と version の部分は、ファイル内のメタデータに保存されている" +"値に合致しなければなりません。" -#: ../source/specifications/version-specifiers.rst:101 +#: ../source/specifications/source-distribution-format.rst:45 +#, fuzzy 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." +"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 :" +"term:`build backend `." msgstr "" +"ソースコード配布物を生成するソースコードは、この仕様に合致した名前をファイル" +"に与えなければなりません。これは、ビルドバックエンドの ``build_sdist`` フック" +"にも当てはまります。" -#: ../source/specifications/version-specifiers.rst:105 +#: ../source/specifications/source-distribution-format.rst:49 msgid "" -"Accordingly, some of the versioning practices which are technically " -"permitted by the specification are strongly discouraged for new projects. " -"Where this is the case, the relevant details are noted in the following " -"sections." +"Code that processes source distribution files MAY recognise source " +"distribution files by the ``.tar.gz`` suffix and the presence of precisely " +"*one* hyphen in the filename. Code that does this may then use the " +"distribution name and version from the filename without further verification." msgstr "" +"ソースコード配布物を生成するソースコードは、 ``.tar.gz`` 拡張子がついていて" +"ファイル名の中に正確に *ひとつ* のハイフンが存在していることを以て、ソース" +"コード配布物のファイルであると認識しても構いません。これを行うソースコード" +"は、この場合には、ファイル名から得た配布物の名前とバージョンをそれ以上の検証" +"をせずに使用しても構いません。" -#: ../source/specifications/version-specifiers.rst:116 -msgid "Local version identifiers MUST comply with the following scheme::" -msgstr "" +#: ../source/specifications/source-distribution-format.rst:55 +msgid "Source distribution file format" +msgstr "ソースコード配布物のファイルフォーマット" -#: ../source/specifications/version-specifiers.rst:120 +#: ../source/specifications/source-distribution-format.rst:57 +#, fuzzy msgid "" -"They consist of a normal public version identifier (as defined in the " -"previous section), along with an arbitrary \"local version label\", " -"separated from the public version identifier by a plus. Local version labels " -"have no specific semantics assigned, but some syntactic restrictions are " -"imposed." +"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:`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``) と言う名前の単一のトップレベルディレクトリがあって、そこにパッ" +"ケージのソールファイル群を含んでいます。 name と version は、ファイル内のメタ" +"データと合致していなければなりません。このディレクトリは、 :ref:`declaring-" +"build-dependencies` の中で定義されたフォーマットで書かれた :file:`pyproject." +"toml` ファイルや、 :ref:`core-metadata` 仕様内に記述されたフォーマットで書か" +"れたメタデータを含んだ ``PKG-INFO`` ファイルも含んでいなければなりません。メ" +"タデータは、少なくともバージョン 2.2 のメタデータ仕様を満足するものでなければ" +"なりません。" -#: ../source/specifications/version-specifiers.rst:125 +#: ../source/specifications/source-distribution-format.rst:65 msgid "" -"Local version identifiers are used to denote fully API (and, if applicable, " -"ABI) compatible patched versions of upstream projects. For example, these " -"may be created by application developers and system integrators by applying " -"specific backported bug fixes when upgrading to a new upstream release would " -"be too disruptive to the application or other integrated system (such as a " -"Linux distribution)." +"No other content of a sdist is required or defined. Build systems can store " +"whatever information they need in the sdist to build the project." msgstr "" +"sdist の他の内容については必須でもなく定義もされていません。ビルドシステム" +"は、プロジェクトをビルドするのに必要なものであればどんな情報でも sdist 内に保" +"存しておくことができます。" -#: ../source/specifications/version-specifiers.rst:132 +#: ../source/specifications/source-distribution-format.rst:68 msgid "" -"The inclusion of the local version label makes it possible to differentiate " -"upstream releases from potentially altered rebuilds by downstream " -"integrators. The use of a local version identifier does not affect the kind " -"of a release but, when applied to a source distribution, does indicate that " -"it may not contain the exact same code as the corresponding upstream release." +"The tarball should use the modern POSIX.1-2001 pax tar format, which " +"specifies UTF-8 based file names. In particular, source distribution files " +"must be readable using the standard library tarfile module with the open " +"flag 'r:gz'." msgstr "" +"tar ボールでは、ファイル名に UTF-8 を使える近代的な POSIX.1-2001 pax tar " +"フォーマットを使用するべきです。とりわけ、ソースコード配布物のファイル群は、" +"標準ライブラリの tarfile モジュールに open flag 'r:gz' を与えることで読み込め" +"るものでなければなりません。" -#: ../source/specifications/version-specifiers.rst:138 +#: ../source/specifications/source-distribution-format.rst:76 +msgid "Source distribution archive features" +msgstr "ソースコード配布物アーカイブの機能" + +#: ../source/specifications/source-distribution-format.rst:78 msgid "" -"To ensure local version identifiers can be readily incorporated as part of " -"filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " -"hash representations, local version labels MUST be limited to the following " -"set of permitted characters:" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." msgstr "" +"tar ファイルをそのまま展開することは危険を伴うため、また、展開結果がプラット" +"フォーム依存になるため、ソースコード配布物アーカイブの機能は制限されていま" +"す。" -#: ../source/specifications/version-specifiers.rst:143 -msgid "ASCII letters (``[a-zA-Z]``)" -msgstr "" +#: ../source/specifications/source-distribution-format.rst:82 +msgid "Unpacking with the data filter" +msgstr "データフィルタしながらアンパックする" -#: ../source/specifications/version-specifiers.rst:144 -msgid "ASCII digits (``[0-9]``)" +#: ../source/specifications/source-distribution-format.rst:84 +msgid "" +"When extracting a source distribution, tools MUST either use :py:func:" +"`tarfile.data_filter` (e.g. :py:meth:`TarFile.extractall(..., filter='data') " +"`), OR follow the *Unpacking without the data " +"filter* section below." msgstr "" +"ソースコード配布物を展開する時には、ツール類は、 :py:func:`tarfile." +"data_filter` (例えば :py:meth:`TarFile.extractall(..., filter='data') " +"`) か、あるいは、後述する *データフィルタなしでア" +"ンパックする* 節に従うか、いずれかを行わな" +"ければなりません。" -#: ../source/specifications/version-specifiers.rst:145 -msgid "periods (``.``)" +#: ../source/specifications/source-distribution-format.rst:88 +msgid "" +"As an exception, on Python interpreters without :py:func:`hasattr(tarfile, " +"'data_filter') ` (:pep:`706`), tools that normally use " +"that filter (directly on indirectly) MAY warn the user and ignore this " +"specification. The trade-off between usability (e.g. fully trusting the " +"archive) and security (e.g. refusing to unpack) is left up to the tool in " +"this case." msgstr "" +"例外として、 :py:func:`hasattr(tarfile, 'data_filter') ` (:pep:`706`) を持たない Python インタープリタ上では、通常ならそ" +"のようなフィルタを使うはずのツール類はユーザに対して警告した上でこの仕様を無" +"視しても構いません。利便性 (例えばアーカイブを完全に信頼すること) とセキュリ" +"ティ (例えばアンパックすることを拒否すること) の間のトレードオフは、この場合" +"にはツールに委ねられています。" -#: ../source/specifications/version-specifiers.rst:147 -#, fuzzy -msgid "Local version labels MUST start and end with an ASCII letter or digit." -msgstr "先頭と最後の文字がASCII文字ないし数字であること。" +#: ../source/specifications/source-distribution-format.rst:96 +msgid "Unpacking without the data filter" +msgstr "データフィルタなしでアンパックする" -#: ../source/specifications/version-specifiers.rst:149 +#: ../source/specifications/source-distribution-format.rst:98 msgid "" -"Comparison and ordering of local versions considers each segment of the " -"local version (divided by a ``.``) separately. If a segment consists " -"entirely of ASCII digits then that section should be considered an integer " -"for comparison purposes and if a segment contains any ASCII letters then " -"that segment is compared lexicographically with case insensitivity. When " -"comparing a numeric and lexicographic segment, the numeric section always " -"compares as greater than the lexicographic segment. Additionally a local " -"version with a great number of segments will always compare as greater than " -"a local version with fewer segments, as long as the shorter local version's " -"segments match the beginning of the longer local version's segments exactly." +"Tools that do not use the ``data`` filter directly (e.g. for backwards " +"compatibility, allowing additional features, or not using Python) MUST " +"follow this section. (At the time of this writing, the ``data`` filter also " +"follows this section, but it may get out of sync in the future.)" msgstr "" +"(例えば、後方互換性のためであったり、追加的な機能を許容するためであったり、あ" +"るいは Python を使わない場合であったりで) ``データ `` フィルタを直接に" +"は使わないツール類は、この節の内容に従わなければなりません。(執筆時点では、 " +"``データ `` フィルタもこの節の内容に従うものになっていますが、将来には" +"この同期が外れるかもしれません。)" -#: ../source/specifications/version-specifiers.rst:160 +#: ../source/specifications/source-distribution-format.rst:104 msgid "" -"An \"upstream project\" is a project that defines its own public versions. A " -"\"downstream project\" is one which tracks and redistributes an upstream " -"project, potentially backporting security and bug fixes from later versions " -"of the upstream project." +"The following files are invalid in an *sdist* archive. Upon encountering " +"such an entry, tools SHOULD notify the user, MUST NOT unpack the entry, and " +"MAY abort with a failure:" msgstr "" +"以下に述べるファイル群は、 *sdist* アーカイブの中に置くには不適格です。そのよ" +"うなエントリに遭遇した場合には、ツール類はユーザに通知するべきであり、そのエ" +"ントリをアンパックしてはならず、そして、エラー (failure) とともに処理を中断し" +"ても構いません:" -#: ../source/specifications/version-specifiers.rst:165 -msgid "" -"Local version identifiers SHOULD NOT be used when publishing upstream " -"projects to a public index server, but MAY be used to identify private " -"builds created directly from the project source. Local version identifiers " -"SHOULD be used by downstream projects when releasing a version that is API " -"compatible with the version of the upstream project identified by the public " -"version identifier, but contains additional changes (such as bug fixes). As " -"the Python Package Index is intended solely for indexing and hosting " -"upstream projects, it MUST NOT allow the use of local version identifiers." -msgstr "" +#: ../source/specifications/source-distribution-format.rst:108 +msgid "Files that would be placed outside the destination directory." +msgstr "宛先となるディレクトリの外側に置かれるファイル群。" -#: ../source/specifications/version-specifiers.rst:175 -msgid "" -"Source distributions using a local version identifier SHOULD provide the " -"``python.integrator`` extension metadata (as defined in :pep:`459`)." +#: ../source/specifications/source-distribution-format.rst:109 +msgid "Links (symbolic or hard) pointing outside the destination directory." msgstr "" +"宛先となるディレクトリの外側を指し示すリンク (シンボリックでもハードでも)。" -#: ../source/specifications/version-specifiers.rst:180 -#, fuzzy -msgid "Final releases" -msgstr "リリースを公開する" +#: ../source/specifications/source-distribution-format.rst:110 +msgid "Device files (including pipes)." +msgstr "デバイスファイル (パイプを含む)。" -#: ../source/specifications/version-specifiers.rst:182 +#: ../source/specifications/source-distribution-format.rst:112 msgid "" -"A version identifier that consists solely of a release segment and " -"optionally an epoch identifier is termed a \"final release\"." +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" msgstr "" +"以下に示すものもまた、不適格です。ツール類はこれらを上記のように扱っても構い" +"ませんが、そうすることを要求されているわけではありません:" -#: ../source/specifications/version-specifiers.rst:185 +#: ../source/specifications/source-distribution-format.rst:115 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "ファイル名の一部に ``..`` を含むファイルまたはリンクのターゲット。" + +#: ../source/specifications/source-distribution-format.rst:116 +msgid "Links pointing to a file that is not part of the archive." +msgstr "当該アーカイブの一部ではないファイルを指し示すリンク。" + +#: ../source/specifications/source-distribution-format.rst:118 msgid "" -"The release segment consists of one or more non-negative integer values, " -"separated by dots::" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." msgstr "" +"ツール類は、アーカイブから得た内容を使って、リンク類 (シンボリックまたはハー" +"ド) をアンパックしても構いません。" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/source-distribution-format.rst:121 +msgid "When extracting *sdist* archives:" +msgstr "*sdist* アーカイブを展開する時:" + +#: ../source/specifications/source-distribution-format.rst:123 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." +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" msgstr "" +"ファイル名の先頭のスラッシュは、必ず削除しなければなりません。 (これは、 " +"``tar`` を展開する時の今日的な標準的な振る舞いです。)" -#: ../source/specifications/version-specifiers.rst:194 -msgid "" -"Comparison and ordering of release segments considers the numeric value of " -"each component of the release segment in turn. When comparing release " -"segments with different numbers of components, the shorter segment is padded " -"out with additional zeros as necessary." +#: ../source/specifications/source-distribution-format.rst:125 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" msgstr "" +"``モード `` (UNIXでのパーミッション) の各ビットについて、ツール類は以下" +"のうちのいずれかをしなければなりません:" -#: ../source/specifications/version-specifiers.rst:199 -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\")." +#: ../source/specifications/source-distribution-format.rst:127 +msgid "use the platform's default for a new file/directory (respectively)," msgstr "" +"プラットフォームの既定値を新しく作るファイル/ディレクトリに (それぞれ) 適用す" +"るか、" -#: ../source/specifications/version-specifiers.rst:203 -msgid "For example::" -msgstr "例えば::" +#: ../source/specifications/source-distribution-format.rst:128 +msgid "set the bit according to the archive, or" +msgstr "アーカイブにおける (パーミッション) ビットに従って設定するか、または、" -#: ../source/specifications/version-specifiers.rst:218 +#: ../source/specifications/source-distribution-format.rst:129 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." +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." msgstr "" +"非実行ファイルには ``rw-r--r--`` (``0o644``) の (パーミッション) ビットを設定" +"し、実行ファイルとディレクトリには ``rwxr-xr-x`` (``0o755``) を設定する。" -#: ../source/specifications/version-specifiers.rst:224 -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 " -"``X.Y.0`` when comparing it to any release segment that includes three " -"components." +#: ../source/specifications/source-distribution-format.rst:132 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." msgstr "" +"特殊な ``モード `` ビット (setups, setgid, sticky) については、削除 (ク" +"リア) しなければなりません。" -#: ../source/specifications/version-specifiers.rst:229 -msgid "" -"Date based release segments are also permitted. An example of a date based " -"release scheme using the year and month of the release::" +#: ../source/specifications/source-distribution-format.rst:133 +msgid "It is RECOMMENDED to preserve the user *executable* bit." msgstr "" +"ユーザ (多分オーナのこと) *実行* ビットについては、そのまま保存することが推奨" +"されています。" -#: ../source/specifications/version-specifiers.rst:241 -#, fuzzy -msgid "Pre-releases" -msgstr "リリース前のバージョン付与方式" +#: ../source/specifications/source-distribution-format.rst:137 +msgid "Further hints" +msgstr "さらなるヒント" -#: ../source/specifications/version-specifiers.rst:243 +#: ../source/specifications/source-distribution-format.rst:139 msgid "" -"Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " -"support testing by their users prior to a final release." +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." msgstr "" +"ツールの作成者は、自分たちのツールに適用する ``tarfile`` 説明文書の中に、*さ" +"らなる検証を行うためのヒント集* を含めることを検討するように推奨されていま" +"す。" -#: ../source/specifications/version-specifiers.rst:246 +#: ../source/specifications/source-distribution-format.rst:146 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::" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." msgstr "" -#: ../source/specifications/version-specifiers.rst:254 -msgid "" -"A version identifier that consists solely of a release segment and a pre-" -"release segment is termed a \"pre-release\"." -msgstr "" +#: ../source/specifications/source-distribution-format.rst:148 +#, fuzzy +msgid "July 2021: Defined what a source tree is." +msgstr "2021-07: ソースコードツリーとは何であるかを定義" -#: ../source/specifications/version-specifiers.rst:257 +#: ../source/specifications/source-distribution-format.rst:149 +#, fuzzy 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 " -"given release are ordered first by phase (alpha, beta, release candidate) " -"and then by the numerical component within that phase." -msgstr "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "2022-09: ソースコード配布物のファイル名について標準化 (:pep:`625`)" -#: ../source/specifications/version-specifiers.rst:262 +#: ../source/specifications/source-distribution-format.rst:151 +#, fuzzy msgid "" -"Installation tools MAY accept both ``c`` and ``rc`` releases for a common " -"release segment in order to handle some existing legacy distributions." +"August 2023: Source distribution archive features were standardized through :" +"pep:`721`." msgstr "" +"2023-08: ソースコード配布物のアーカイブの機能について標準化 (: pep:`721`)" -#: ../source/specifications/version-specifiers.rst:265 -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:7 +#: ../source/specifications/version-specifiers.rst:780 +msgid "Version specifiers" +msgstr "バージョン指定子" -#: ../source/specifications/version-specifiers.rst:268 +#: ../source/specifications/version-specifiers.rst:10 msgid "" -"Build tools, publication tools and index servers SHOULD disallow the " -"creation of both ``rc`` and ``c`` releases for a common release segment." +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:273 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy -msgid "Post-releases" -msgstr "zest.releaser" +msgid "Definitions" +msgstr "仕様型文書" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:17 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)." +"The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " +"NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " +"\"OPTIONAL\" in this document are to be interpreted as described in :rfc:" +"`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:279 +#: ../source/specifications/version-specifiers.rst:21 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::" +"\"Build tools\" are automated tools intended to run on development systems, " +"producing source and binary distribution archives. Build tools may also be " +"invoked by integration tools in order to build software distributed as " +"sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:284 +#: ../source/specifications/version-specifiers.rst:26 msgid "" -"A version identifier that includes a post-release segment without a " -"developmental release segment is termed a \"post-release\"." +"\"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:287 +#: ../source/specifications/version-specifiers.rst:29 msgid "" -"The post-release segment consists of the string ``.post``, followed by a non-" -"negative integer value. Post-releases are ordered by their numerical " -"component, immediately following the corresponding release, and ahead of any " -"subsequent release." +"\"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:294 +#: ../source/specifications/version-specifiers.rst:32 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 " -"release number and increment the final component for each maintenance " -"release." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:299 -msgid "Post-releases are also permitted for pre-releases::" +"\"Installation tools\" are integration tools specifically intended to run on " +"deployment targets, consuming source and binary distribution archives from " +"an index server or other designated location and deploying them to the " +"target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:307 +#: ../source/specifications/version-specifiers.rst:37 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 " -"is substantially clearer to simply create a new pre-release by incrementing " -"the numeric component." +"\"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:314 -msgid "Developmental releases" -msgstr "" +#: ../source/specifications/version-specifiers.rst:43 +#, fuzzy +msgid "Version scheme" +msgstr "バージョン指定子" -#: ../source/specifications/version-specifiers.rst:316 +#: ../source/specifications/version-specifiers.rst:45 msgid "" -"Some projects make regular developmental releases, and system packagers " -"(especially for Linux distributions) may wish to create early releases " -"directly from source control which do not conflict with later project " -"releases." +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:321 +#: ../source/specifications/version-specifiers.rst:48 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::" +"The version scheme is used both to describe the distribution version " +"provided by a particular distribution archive, as well as to place " +"constraints on the version of dependencies needed in order to build or run " +"the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:327 +#: ../source/specifications/version-specifiers.rst:57 +#, fuzzy +msgid "Public version identifiers" +msgstr "ローカルのバージョン指定子" + +#: ../source/specifications/version-specifiers.rst:59 msgid "" -"A version identifier that includes a developmental release segment is termed " -"a \"developmental release\"." +"The canonical public version identifiers MUST comply with the following " +"scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:330 -msgid "" -"The developmental release segment consists of the string ``.dev``, followed " -"by a non-negative integer value. Developmental releases are ordered by their " -"numerical component, immediately before the corresponding release (and " -"before any pre-releases with the same release segment), and following any " -"previous release (including any post-releases)." +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:336 -msgid "" -"Developmental releases are also permitted for pre-releases and post-" -"releases::" +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:346 +#: ../source/specifications/version-specifiers.rst:68 msgid "" -"While they may be useful for continuous integration purposes, publishing " -"developmental releases of pre-releases to general purpose public index " -"servers is strongly discouraged, as it makes the version identifier " -"difficult to parse for human readers. If such a release needs to be " -"published, it is substantially clearer to instead create a new pre-release " -"by incrementing the numeric component." +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:353 +#: ../source/specifications/version-specifiers.rst:73 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." +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:359 -#, fuzzy -msgid "Version epochs" -msgstr "バージョン指定子" +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" -#: ../source/specifications/version-specifiers.rst:361 -msgid "" -"If included in a version identifier, the epoch appears before all other " -"components, separated from the release segment by an exclamation mark::" +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:366 -msgid "If no explicit epoch is given, the implicit epoch is ``0``." +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:368 -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 " -"way that means the normal version ordering rules will give the wrong answer. " -"For example, if a project is using date based versions like ``2014.04`` and " -"would like to switch to semantic versions like ``1.0``, then the new " -"releases would be identified as *older* than the date based releases when " -"using the normal sorting scheme::" +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:382 -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::" +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:396 -msgid "Normalization" -msgstr "正規化" +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" -#: ../source/specifications/version-specifiers.rst:398 +#: ../source/specifications/version-specifiers.rst:86 msgid "" -"In order to maintain better compatibility with existing versions there are a " -"number of \"alternative\" syntaxes that MUST be taken into account when " -"parsing versions. These syntaxes MUST be considered when parsing a version, " -"however they should be \"normalized\" to the standard syntax defined above." +"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:405 -msgid "Case sensitivity" +#: ../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:407 +#: ../source/specifications/version-specifiers.rst:92 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``." +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:413 -#, fuzzy -msgid "Integer Normalization" -msgstr "正規化" - -#: ../source/specifications/version-specifiers.rst:415 +#: ../source/specifications/version-specifiers.rst:95 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`` " -"would normalize to ``0`` while ``09000`` would normalize to ``9000``. This " -"does not hold true for integers inside of an alphanumeric segment of a local " -"version such as ``1.0+foo0100`` which is already in its normalized form." +"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:423 -#, fuzzy -msgid "Pre-release separators" -msgstr "リリース前のバージョン付与方式" - -#: ../source/specifications/version-specifiers.rst:425 +#: ../source/specifications/version-specifiers.rst:101 msgid "" -"Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " -"release segment and the pre-release segment. The normal form for this is " -"without a separator. This allows versions such as ``1.1.a1`` or ``1.1-a1`` " -"which would be normalized to ``1.1a1``. It should also allow a separator to " -"be used between the pre-release signifier and the numeral. This allows " -"versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." +"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:434 -#, fuzzy -msgid "Pre-release spelling" -msgstr "リリース前のバージョン付与方式" - -#: ../source/specifications/version-specifiers.rst:436 +#: ../source/specifications/version-specifiers.rst:105 msgid "" -"Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " -"``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " -"respectively. This allows versions such as ``1.1alpha1``, ``1.1beta2``, or " -"``1.1c3`` which normalize to ``1.1a1``, ``1.1b2``, and ``1.1rc3``. In every " -"case the additional spelling should be considered equivalent to their normal " -"forms." +"Accordingly, some of the versioning practices which are technically " +"permitted by the specification are strongly discouraged for new projects. " +"Where this is the case, the relevant details are noted in the following " +"sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:445 -msgid "Implicit pre-release number" +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:447 +#: ../source/specifications/version-specifiers.rst:120 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`` " -"explicitly. This allows versions such as ``1.2a`` which is normalized to " -"``1.2a0``." +"They consist of a normal public version identifier (as defined in the " +"previous section), along with an arbitrary \"local version label\", " +"separated from the public version identifier by a plus. Local version labels " +"have no specific semantics assigned, but some syntactic restrictions are " +"imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:453 -msgid "Post release separators" +#: ../source/specifications/version-specifiers.rst:125 +msgid "" +"Local version identifiers are used to denote fully API (and, if applicable, " +"ABI) compatible patched versions of upstream projects. For example, these " +"may be created by application developers and system integrators by applying " +"specific backported bug fixes when upgrading to a new upstream release would " +"be too disruptive to the application or other integrated system (such as a " +"Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:455 +#: ../source/specifications/version-specifiers.rst:132 msgid "" -"Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " -"the separator all together. The normal form of this is with the ``.`` " -"separator. This allows versions such as ``1.2-post2`` or ``1.2post2`` which " -"normalize to ``1.2.post2``. Like the pre-release separator this also allows " -"an optional separator between the post release signifier and the numeral. " -"This allows versions like ``1.2.post-2`` which would normalize to ``1.2." -"post2``." +"The inclusion of the local version label makes it possible to differentiate " +"upstream releases from potentially altered rebuilds by downstream " +"integrators. The use of a local version identifier does not affect the kind " +"of a release but, when applied to a source distribution, does indicate that " +"it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:464 -#, fuzzy -msgid "Post release spelling" -msgstr "リリース前のバージョン付与方式" - -#: ../source/specifications/version-specifiers.rst:466 +#: ../source/specifications/version-specifiers.rst:138 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 " -"with the pre-releases the additional spellings should be considered " -"equivalent to their normal forms." +"To ensure local version identifiers can be readily incorporated as part of " +"filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " +"hash representations, local version labels MUST be limited to the following " +"set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:473 -msgid "Implicit post release number" +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:475 -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`` " -"explicitly. This allows versions such as ``1.2.post`` which is normalized to " -"``1.2.post0``." +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:481 -msgid "Implicit post releases" +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:483 -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 " -"allows versions such as ``1.0-1`` to be normalized to ``1.0.post1``. This " -"particular normalization MUST NOT be used in conjunction with the implicit " -"post release number rule. In other words, ``1.0-`` is *not* a valid version " -"and it does *not* normalize to ``1.0.post0``." -msgstr "" +#: ../source/specifications/version-specifiers.rst:147 +#, fuzzy +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "先頭と最後の文字がASCII文字ないし数字であること。" -#: ../source/specifications/version-specifiers.rst:492 -msgid "Development release separators" +#: ../source/specifications/version-specifiers.rst:149 +msgid "" +"Comparison and ordering of local versions considers each segment of the " +"local version (divided by a ``.``) separately. If a segment consists " +"entirely of ASCII digits then that section should be considered an integer " +"for comparison purposes and if a segment contains any ASCII letters then " +"that segment is compared lexicographically with case insensitivity. When " +"comparing a numeric and lexicographic segment, the numeric section always " +"compares as greater than the lexicographic segment. Additionally a local " +"version with a great number of segments will always compare as greater than " +"a local version with fewer segments, as long as the shorter local version's " +"segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:494 +#: ../source/specifications/version-specifiers.rst:160 msgid "" -"Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " -"omitting the separator all together. The normal form of this is with the ``." -"`` separator. This allows versions such as ``1.2-dev2`` or ``1.2dev2`` which " -"normalize to ``1.2.dev2``." +"An \"upstream project\" is a project that defines its own public versions. A " +"\"downstream project\" is one which tracks and redistributes an upstream " +"project, potentially backporting security and bug fixes from later versions " +"of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:501 -msgid "Implicit development release number" +#: ../source/specifications/version-specifiers.rst:165 +msgid "" +"Local version identifiers SHOULD NOT be used when publishing upstream " +"projects to a public index server, but MAY be used to identify private " +"builds created directly from the project source. Local version identifiers " +"SHOULD be used by downstream projects when releasing a version that is API " +"compatible with the version of the upstream project identified by the public " +"version identifier, but contains additional changes (such as bug fixes). As " +"the Python Package Index is intended solely for indexing and hosting " +"upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:503 +#: ../source/specifications/version-specifiers.rst:175 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 " -"``0`` explicitly. This allows versions such as ``1.2.dev`` which is " -"normalized to ``1.2.dev0``." +"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:510 +#: ../source/specifications/version-specifiers.rst:180 #, fuzzy -msgid "Local version segments" -msgstr "ローカルのバージョン指定子" +msgid "Final releases" +msgstr "リリースを公開する" -#: ../source/specifications/version-specifiers.rst:512 +#: ../source/specifications/version-specifiers.rst:182 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 " -"using the ``.`` character. This allows versions such as ``1.0+ubuntu-1`` to " -"be normalized to ``1.0+ubuntu.1``." +"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:519 -msgid "Preceding v character" +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:521 +#: ../source/specifications/version-specifiers.rst:190 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 " -"for all purposes and should be omitted from all normalized forms of the " -"version. The same version with and without the ``v`` is considered " -"equivalent." +"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:528 -msgid "Leading and Trailing Whitespace" +#: ../source/specifications/version-specifiers.rst:194 +msgid "" +"Comparison and ordering of release segments considers the numeric value of " +"each component of the release segment in turn. When comparing release " +"segments with different numbers of components, the shorter segment is padded " +"out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:530 +#: ../source/specifications/version-specifiers.rst:199 msgid "" -"Leading and trailing whitespace must be silently ignored and removed from " -"all normalized forms of a version. This includes ``\" \"``, ``\\t``, " -"``\\n``, ``\\r``, ``\\f``, and ``\\v``. This allows accidental whitespace to " -"be handled sensibly, such as a version like ``1.0\\n`` which normalizes to " -"``1.0``." +"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:537 -#, fuzzy -msgid "Examples of compliant version schemes" -msgstr "規定に合致したバージョン番号の例を次に示す::" +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "例えば::" -#: ../source/specifications/version-specifiers.rst:539 +#: ../source/specifications/version-specifiers.rst:218 msgid "" -"The standard version scheme is designed to encompass a wide range of " -"identification practices across public and private Python projects. In " -"practice, a single project attempting to use the full flexibility offered by " -"the scheme would create a situation where human users had difficulty " -"figuring out the relative order of versions, even though the rules above " -"ensure all compliant tools will order them consistently." +"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:546 +#: ../source/specifications/version-specifiers.rst:224 msgid "" -"The following examples illustrate a small selection of the different " -"approaches projects may choose to identify their releases, while still " -"ensuring that the \"latest release\" and the \"latest stable release\" can " -"be easily determined, both by human users and automated tools." +"``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 " +"``X.Y.0`` when comparing it to any release segment that includes three " +"components." msgstr "" -#: ../source/specifications/version-specifiers.rst:551 +#: ../source/specifications/version-specifiers.rst:229 +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:241 #, fuzzy -msgid "Simple \"major.minor\" versioning::" -msgstr "一連番号によるバージョン付与" +msgid "Pre-releases" +msgstr "リリース前のバージョン付与方式" -#: ../source/specifications/version-specifiers.rst:560 -msgid "Simple \"major.minor.micro\" versioning::" +#: ../source/specifications/version-specifiers.rst:243 +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:568 +#: ../source/specifications/version-specifiers.rst:246 msgid "" -"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +"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:580 +#: ../source/specifications/version-specifiers.rst:254 msgid "" -"\"major.minor\" versioning with developmental releases, release candidates " -"and post-releases for minor corrections::" +"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:595 +#: ../source/specifications/version-specifiers.rst:257 msgid "" -"Date based releases, using an incrementing serial within each year, skipping " -"zero::" +"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 " +"given release are ordered first by phase (alpha, beta, release candidate) " +"and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:609 -msgid "Summary of permitted suffixes and relative ordering" +#: ../source/specifications/version-specifiers.rst:262 +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:613 +#: ../source/specifications/version-specifiers.rst:265 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." +"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:617 +#: ../source/specifications/version-specifiers.rst:268 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``." +"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:621 +#: ../source/specifications/version-specifiers.rst:273 +#, fuzzy +msgid "Post-releases" +msgstr "zest.releaser" + +#: ../source/specifications/version-specifiers.rst:275 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::" +"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:627 +#: ../source/specifications/version-specifiers.rst:279 msgid "" -"All release segments involved in the comparison MUST be converted to a " -"consistent length by padding shorter segments with zeros as needed." +"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:630 +#: ../source/specifications/version-specifiers.rst:284 msgid "" -"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " -"permitted and MUST be ordered as shown::" +"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:635 +#: ../source/specifications/version-specifiers.rst:287 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 " -"same ``N`` for both a ``c`` and a ``rc`` in the same release segment as " -"ambiguous and remain in compliance with the specification." +"The post-release segment consists of the string ``.post``, followed by a non-" +"negative integer value. Post-releases are ordered by their numerical " +"component, immediately following the corresponding release, and ahead of any " +"subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:640 +#: ../source/specifications/version-specifiers.rst:294 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::" +"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 " +"release number and increment the final component for each maintenance " +"release." msgstr "" -#: ../source/specifications/version-specifiers.rst:646 -msgid "" -"Within a post-release (``1.0.post1``), the following suffixes are permitted " -"and MUST be ordered as shown::" +#: ../source/specifications/version-specifiers.rst:299 +msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:307 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``)." +"Creating post-releases of pre-releases is strongly discouraged, as it makes " +"the version identifier difficult to parse for human readers. In general, it " +"is substantially clearer to simply create a new pre-release by incrementing " +"the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:655 +#: ../source/specifications/version-specifiers.rst:314 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 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." +"Some projects make regular developmental releases, and system packagers " +"(especially for Linux distributions) may wish to create early releases " +"directly from source control which do not conflict with later project " +"releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:658 -msgid "The following example covers many of the possible combinations::" +#: ../source/specifications/version-specifiers.rst:321 +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:683 -msgid "Version ordering across different metadata versions" +#: ../source/specifications/version-specifiers.rst:327 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:330 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`." +"The developmental release segment consists of the string ``.dev``, followed " +"by a non-negative integer value. Developmental releases are ordered by their " +"numerical component, immediately before the corresponding release (and " +"before any pre-releases with the same release segment), and following any " +"previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:689 +#: ../source/specifications/version-specifiers.rst:336 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 " -"was using. Additionally installers required the ability to create a " -"reasonably prioritized list that includes all, or as many as possible, " -"versions of a project to determine which versions it should install. These " -"requirements necessitate a standardization across one parsing mechanism to " -"be used for all versions of a project." +"Developmental releases are also permitted for pre-releases and post-" +"releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:697 +#: ../source/specifications/version-specifiers.rst:346 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 " -"ignore any versions which cannot be parsed by the rules in this " -"specification, but MAY fall back to implementation defined version parsing " -"and ordering schemes if no versions complying with this specification are " -"available." +"While they may be useful for continuous integration purposes, publishing " +"developmental releases of pre-releases to general purpose public index " +"servers is strongly discouraged, as it makes the version identifier " +"difficult to parse for human readers. If such a release needs to be " +"published, it is substantially clearer to instead create a new pre-release " +"by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:703 +#: ../source/specifications/version-specifiers.rst:353 msgid "" -"Distribution users may wish to explicitly remove non-compliant versions from " -"any private package indexes they control." +"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:708 +#: ../source/specifications/version-specifiers.rst:359 #, fuzzy -msgid "Compatibility with other version schemes" -msgstr "universal wheelsの取り扱い" +msgid "Version epochs" +msgstr "バージョン指定子" -#: ../source/specifications/version-specifiers.rst:710 +#: ../source/specifications/version-specifiers.rst:361 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 " -"specification. In such cases, the project specific version can be stored in " -"the metadata while the translated public version is published in the version " -"field." +"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:715 -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." +#: ../source/specifications/version-specifiers.rst:366 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:723 +#: ../source/specifications/version-specifiers.rst:368 msgid "" -"`Semantic versioning`_ is a popular version identification scheme that is " -"more prescriptive than this specification regarding the significance of " -"different elements of a release number. Even if a project chooses not to " -"abide by the details of semantic versioning, the scheme is worth " -"understanding as it covers many of the issues that can arise when depending " -"on other distributions, and when publishing a distribution that others rely " -"on." +"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 " +"way that means the normal version ordering rules will give the wrong answer. " +"For example, if a project is using date based versions like ``2014.04`` and " +"would like to switch to semantic versions like ``1.0``, then the new " +"releases would be identified as *older* than the date based releases when " +"using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:730 +#: ../source/specifications/version-specifiers.rst:382 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 " -"specification) are fully compatible with the version scheme defined in this " -"specification, and abiding by these aspects is encouraged." +"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:735 +#: ../source/specifications/version-specifiers.rst:396 +msgid "Normalization" +msgstr "正規化" + +#: ../source/specifications/version-specifiers.rst:398 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." +"In order to maintain better compatibility with existing versions there are a " +"number of \"alternative\" syntaxes that MUST be taken into account when " +"parsing versions. These syntaxes MUST be considered when parsing a version, " +"however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 -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." +#: ../source/specifications/version-specifiers.rst:405 +msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:743 +#: ../source/specifications/version-specifiers.rst:407 msgid "" -"Specific build information may also be included in local version labels." +"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:749 +#: ../source/specifications/version-specifiers.rst:413 #, fuzzy -msgid "DVCS based version labels" -msgstr "日付ベースのバージョン付与" +msgid "Integer Normalization" +msgstr "正規化" -#: ../source/specifications/version-specifiers.rst:751 +#: ../source/specifications/version-specifiers.rst:415 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. " -"As hashes cannot be ordered reliably such versions are not permitted in the " -"public version field." +"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`` " +"would normalize to ``0`` while ``09000`` would normalize to ``9000``. This " +"does not hold true for integers inside of an alphanumeric segment of a local " +"version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 -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:423 +#, fuzzy +msgid "Pre-release separators" +msgstr "リリース前のバージョン付与方式" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:425 msgid "" -"Identifying hash information may also be included in local version labels." +"Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " +"release segment and the pre-release segment. The normal form for this is " +"without a separator. This allows versions such as ``1.1.a1`` or ``1.1-a1`` " +"which would be normalized to ``1.1a1``. It should also allow a separator to " +"be used between the pre-release signifier and the numeral. This allows " +"versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:764 +#: ../source/specifications/version-specifiers.rst:434 #, fuzzy -msgid "Olson database versioning" -msgstr "日付ベースのバージョン付与" +msgid "Pre-release spelling" +msgstr "リリース前のバージョン付与方式" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:436 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." +"Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " +"``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " +"respectively. This allows versions such as ``1.1alpha1``, ``1.1beta2``, or " +"``1.1c3`` which normalize to ``1.1a1``, ``1.1b2``, and ``1.1rc3``. In every " +"case the additional spelling should be considered equivalent to their normal " +"forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:770 -msgid "" -"This can be translated to a compliant public version identifier as ``." -"``, where the serial starts at zero or one (for the 'a' " -"release) and is incremented with each subsequent database update within the " -"year." +#: ../source/specifications/version-specifiers.rst:445 +msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:775 +#: ../source/specifications/version-specifiers.rst:447 msgid "" -"As with other translated version identifiers, the corresponding Olson " -"database version could be recorded in the project metadata." +"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`` " +"explicitly. This allows versions such as ``1.2a`` which is normalized to " +"``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:782 -msgid "" -"A version specifier consists of a series of version clauses, separated by " -"commas. For example::" +#: ../source/specifications/version-specifiers.rst:453 +msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 -msgid "The comparison operator determines the kind of version clause:" +#: ../source/specifications/version-specifiers.rst:455 +msgid "" +"Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " +"the separator all together. The normal form of this is with the ``.`` " +"separator. This allows versions such as ``1.2-post2`` or ``1.2post2`` which " +"normalize to ``1.2.post2``. Like the pre-release separator this also allows " +"an optional separator between the post release signifier and the numeral. " +"This allows versions like ``1.2.post-2`` which would normalize to ``1.2." +"post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:789 -msgid "``~=``: `Compatible release`_ clause" -msgstr "" +#: ../source/specifications/version-specifiers.rst:464 +#, fuzzy +msgid "Post release spelling" +msgstr "リリース前のバージョン付与方式" -#: ../source/specifications/version-specifiers.rst:790 -msgid "``==``: `Version matching`_ clause" +#: ../source/specifications/version-specifiers.rst:466 +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 " +"with the pre-releases the additional spellings should be considered " +"equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:791 -msgid "``!=``: `Version exclusion`_ clause" +#: ../source/specifications/version-specifiers.rst:473 +msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:792 -msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +#: ../source/specifications/version-specifiers.rst:475 +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`` " +"explicitly. This allows versions such as ``1.2.post`` which is normalized to " +"``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:793 -msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +#: ../source/specifications/version-specifiers.rst:481 +msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:794 -msgid "``===``: `Arbitrary equality`_ clause." +#: ../source/specifications/version-specifiers.rst:483 +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 " +"allows versions such as ``1.0-1`` to be normalized to ``1.0.post1``. This " +"particular normalization MUST NOT be used in conjunction with the implicit " +"post release number rule. In other words, ``1.0-`` is *not* a valid version " +"and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 -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." +#: ../source/specifications/version-specifiers.rst:492 +msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:800 +#: ../source/specifications/version-specifiers.rst:494 msgid "" -"Whitespace between a conditional operator and the following version " -"identifier is optional, as is the whitespace around the commas." +"Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " +"omitting the separator all together. The normal form of this is with the ``." +"`` separator. This allows versions such as ``1.2-dev2`` or ``1.2dev2`` which " +"normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:803 -msgid "" -"When multiple candidate versions match a version specifier, the preferred " -"version SHOULD be the latest version as determined by the consistent " -"ordering defined by the standard `Version scheme`_. Whether or not pre-" -"releases are considered as candidate versions SHOULD be handled as described " -"in `Handling of pre-releases`_." +#: ../source/specifications/version-specifiers.rst:501 +msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:809 +#: ../source/specifications/version-specifiers.rst:503 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." +"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 " +"``0`` explicitly. This allows versions such as ``1.2.dev`` which is " +"normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:818 -msgid "Compatible release" +#: ../source/specifications/version-specifiers.rst:510 +#, fuzzy +msgid "Local version segments" +msgstr "ローカルのバージョン指定子" + +#: ../source/specifications/version-specifiers.rst:512 +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 " +"using the ``.`` character. This allows versions such as ``1.0+ubuntu-1`` to " +"be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 -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." +#: ../source/specifications/version-specifiers.rst:519 +msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:521 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." +"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 " +"for all purposes and should be omitted from all normalized forms of the " +"version. The same version with and without the ``v`` is considered " +"equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:828 -msgid "" -"For a given release identifier ``V.N``, the compatible release clause is " -"approximately equivalent to the pair of comparison clauses::" +#: ../source/specifications/version-specifiers.rst:528 +msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:833 +#: ../source/specifications/version-specifiers.rst:530 msgid "" -"This operator MUST NOT be used with a single segment version number such as " -"``~=1``." +"Leading and trailing whitespace must be silently ignored and removed from " +"all normalized forms of a version. This includes ``\" \"``, ``\\t``, " +"``\\n``, ``\\r``, ``\\f``, and ``\\v``. This allows accidental whitespace to " +"be handled sensibly, such as a version like ``1.0\\n`` which normalizes to " +"``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:836 +#: ../source/specifications/version-specifiers.rst:537 #, fuzzy -msgid "For example, the following groups of version clauses are equivalent::" -msgstr "次に挙げる名前はすべて同等ということになります:" +msgid "Examples of compliant version schemes" +msgstr "規定に合致したバージョン番号の例を次に示す::" -#: ../source/specifications/version-specifiers.rst:844 +#: ../source/specifications/version-specifiers.rst:539 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::" +"The standard version scheme is designed to encompass a wide range of " +"identification practices across public and private Python projects. In " +"practice, a single project attempting to use the full flexibility offered by " +"the scheme would create a situation where human users had difficulty " +"figuring out the relative order of versions, even though the rules above " +"ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:854 +#: ../source/specifications/version-specifiers.rst:546 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::" +"The following examples illustrate a small selection of the different " +"approaches projects may choose to identify their releases, while still " +"ensuring that the \"latest release\" and the \"latest stable release\" can " +"be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:866 +#: ../source/specifications/version-specifiers.rst:551 #, fuzzy -msgid "Version matching" -msgstr "バージョン指定子" - -#: ../source/specifications/version-specifiers.rst:868 -msgid "" -"A version matching clause includes the version matching operator ``==`` and " -"a version identifier." -msgstr "" +msgid "Simple \"major.minor\" versioning::" +msgstr "一連番号によるバージョン付与" -#: ../source/specifications/version-specifiers.rst:871 -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." +#: ../source/specifications/version-specifiers.rst:560 +msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:875 +#: ../source/specifications/version-specifiers.rst:568 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 " -"version. The *only* substitution performed is the zero padding of the " -"release segment to ensure the release segments are compared with the same " -"length." +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:881 +#: ../source/specifications/version-specifiers.rst:580 msgid "" -"Whether or not strict version matching is appropriate depends on the " -"specific use case for the version specifier. Automated tools SHOULD at least " -"issue warnings and MAY reject them entirely when strict version matches are " -"used inappropriately." +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:886 +#: ../source/specifications/version-specifiers.rst:595 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, then trailing components " -"(or the lack thereof) in the release segment are also ignored." +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:893 -#: ../source/specifications/version-specifiers.rst:954 -msgid "" -"For example, given the version ``1.1.post1``, the following clauses would " -"match or not as shown::" +#: ../source/specifications/version-specifiers.rst:609 +msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:900 +#: ../source/specifications/version-specifiers.rst:613 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::" +"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:908 +#: ../source/specifications/version-specifiers.rst:617 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 " -"identifiers). Given the version ``1.1``, the following clauses would match " -"or not as shown::" +"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:920 +#: ../source/specifications/version-specifiers.rst:621 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 " -"development release segment is always the final segment in the public " -"version, and the local version is ignored for comparison purposes, so using " -"either in a prefix match wouldn't make any sense." +"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:926 +#: ../source/specifications/version-specifiers.rst:627 msgid "" -"The use of ``==`` (without at least the wildcard suffix) when defining " -"dependencies for published distributions is strongly discouraged as it " -"greatly complicates the deployment of security fixes. The strict version " -"comparison operator is intended primarily for use when defining dependencies " -"for repeatable *deployments of applications* while using a shared " -"distribution index." +"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:933 +#: ../source/specifications/version-specifiers.rst:630 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." +"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:937 +#: ../source/specifications/version-specifiers.rst:635 msgid "" -"If the specified version identifier is a local version identifier, then the " -"local version labels of candidate versions MUST be considered when matching " -"versions, with the public version identifier being matched as described " -"above, and the local version label being checked for equivalence using a " -"strict string equality comparison." +"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 " +"same ``N`` for both a ``c`` and a ``rc`` in the same release segment as " +"ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:945 -#, fuzzy -msgid "Version exclusion" -msgstr "バージョン指定子" - -#: ../source/specifications/version-specifiers.rst:947 +#: ../source/specifications/version-specifiers.rst:640 msgid "" -"A version exclusion clause includes the version exclusion operator ``!=`` " -"and a version identifier." +"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:950 +#: ../source/specifications/version-specifiers.rst:646 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:963 -msgid "Inclusive ordered comparison" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:965 +#: ../source/specifications/version-specifiers.rst:651 msgid "" -"An inclusive ordered comparison clause includes a comparison operator and a " -"version identifier, and will match any version where the comparison is " -"correct based on the relative position of the candidate version and the " -"specified version given the consistent ordering defined by the standard " -"`Version scheme`_." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:971 -msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +"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:973 -#: ../source/specifications/version-specifiers.rst:1003 +#: ../source/specifications/version-specifiers.rst:655 msgid "" -"As with version matching, the release segment is zero padded as necessary to " -"ensure the release segments are compared with the same length." +"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:976 -#: ../source/specifications/version-specifiers.rst:1006 -msgid "Local version identifiers are NOT permitted in this version specifier." +#: ../source/specifications/version-specifiers.rst:658 +msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:980 -msgid "Exclusive ordered comparison" +#: ../source/specifications/version-specifiers.rst:683 +msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:982 +#: ../source/specifications/version-specifiers.rst:685 msgid "" -"The exclusive ordered comparisons ``>`` and ``<`` are similar to the " -"inclusive ordered comparisons in that they rely on the relative position of " -"the candidate version and the specified version given the consistent " -"ordering defined by the standard `Version scheme`_. However, they " -"specifically exclude pre-releases, post-releases, and local versions of the " -"specified version." +"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:988 +#: ../source/specifications/version-specifiers.rst:689 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 " -"that releases are later than a particular post release, including additional " -"post releases, by using ``>V.postN``. For example, ``>1.7`` will allow " -"``1.7.1`` but not ``1.7.0.post1`` and ``>1.7.post2`` will allow ``1.7.1`` " -"and ``1.7.0.post3`` but not ``1.7.0``." +"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 " +"was using. Additionally installers required the ability to create a " +"reasonably prioritized list that includes all, or as many as possible, " +"versions of a project to determine which versions it should install. These " +"requirements necessitate a standardization across one parsing mechanism to " +"be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:995 +#: ../source/specifications/version-specifiers.rst:697 msgid "" -"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " -"of the specified version." +"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 " +"ignore any versions which cannot be parsed by the rules in this " +"specification, but MAY fall back to implementation defined version parsing " +"and ordering schemes if no versions complying with this specification are " +"available." msgstr "" -#: ../source/specifications/version-specifiers.rst:998 +#: ../source/specifications/version-specifiers.rst:703 msgid "" -"The exclusive ordered comparison ``." +"``, where the serial starts at zero or one (for the 'a' " +"release) and is incremented with each subsequent database update within the " +"year." msgstr "" -#: ../source/specifications/version-specifiers.rst:1062 +#: ../source/specifications/version-specifiers.rst:775 msgid "" -"Post-releases and final releases receive no special treatment in version " -"specifiers - they are always included unless explicitly excluded." +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:1069 -msgid "``~=3.1``: version 3.1 or later, but not version 4.0 or later." +#: ../source/specifications/version-specifiers.rst:782 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1070 -msgid "``~=3.1.2``: version 3.1.2 or later, but not version 3.2.0 or later." +#: ../source/specifications/version-specifiers.rst:787 +msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1071 -msgid "``~=3.1a1``: version 3.1a1 or later, but not version 4.0 or later." +#: ../source/specifications/version-specifiers.rst:789 +msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:1072 -msgid "" -"``== 3.1``: specifically version 3.1 (or 3.1.0), excludes all pre-releases, " -"post releases, developmental releases and any 3.1.x maintenance releases." +#: ../source/specifications/version-specifiers.rst:790 +msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:1074 -msgid "" -"``== 3.1.*``: any version that starts with 3.1. Equivalent to the " -"``~=3.1.0`` compatible release clause." +#: ../source/specifications/version-specifiers.rst:791 +msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:1076 -msgid "" -"``~=3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3 and not " -"version 3.2.0 or later." +#: ../source/specifications/version-specifiers.rst:792 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:1081 -#, fuzzy -msgid "Direct references" -msgstr "参考文献" - -#: ../source/specifications/version-specifiers.rst:1083 -msgid "" -"Some automated tools may permit the use of a direct reference as an " -"alternative to a normal version specifier. A direct reference consists of " -"the specifier ``@`` and an explicit URL." +#: ../source/specifications/version-specifiers.rst:793 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:1087 -msgid "" -"Whether or not direct references are appropriate depends on the specific use " -"case for the version specifier. Automated tools SHOULD at least issue " -"warnings and MAY reject them entirely when direct references are used " -"inappropriately." +#: ../source/specifications/version-specifiers.rst:794 +msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:1092 +#: ../source/specifications/version-specifiers.rst:796 msgid "" -"Public index servers SHOULD NOT allow the use of direct references in " -"uploaded distributions. Direct references are intended as a tool for " -"software integrators rather than publishers." +"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:1096 +#: ../source/specifications/version-specifiers.rst:800 msgid "" -"Depending on the use case, some appropriate targets for a direct URL " -"reference may be an sdist or a wheel binary archive. The exact URLs and " -"targets supported will be tool dependent." -msgstr "" - -#: ../source/specifications/version-specifiers.rst:1100 -msgid "For example, a local source archive may be referenced directly::" +"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:1104 -msgid "Alternatively, a prebuilt archive may also be referenced::" +#: ../source/specifications/version-specifiers.rst:803 +msgid "" +"When multiple candidate versions match a version specifier, the preferred " +"version SHOULD be the latest version as determined by the consistent " +"ordering defined by the standard `Version scheme`_. Whether or not pre-" +"releases are considered as candidate versions SHOULD be handled as described " +"in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1108 +#: ../source/specifications/version-specifiers.rst:809 msgid "" -"All direct references that do not refer to a local file URL SHOULD specify a " -"secure transport mechanism (such as ``https``) AND include an expected hash " -"value in the URL for verification purposes. If a direct reference is " -"specified without any hash information, with hash information that the tool " -"doesn't understand, or with a selected hash algorithm that the tool " -"considers too weak to trust, automated tools SHOULD at least emit a warning " -"and MAY refuse to rely on the URL. If such a direct reference also uses an " -"insecure transport, automated tools SHOULD NOT rely on the URL." +"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:1117 -#, fuzzy -msgid "" -"It is RECOMMENDED that only hashes which are unconditionally provided by the " -"latest version of the standard library's :py:mod:`hashlib` module be used " -"for source archive hashes. At time of writing, that list consists of " -"``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and " -"``'sha512'``." +#: ../source/specifications/version-specifiers.rst:818 +msgid "Compatible release" msgstr "" -"``hash`` キー (``string`` 型) は、 ``=`` とい" -"う値を伴ってソンゾンしているべきです。標準ライブラリの ``hash lib`` モジュー" -"ルの最新版が無条件に提供するハッシュだけをソースコードアーカイブのハッシュと" -"して使うことを推奨します。本文書の執筆時点では、 'md5' ・ 'sha1' ・ 'sha224' " -"・ 'sha256' ・ 'sha384' ・ 'sha512' が該当します。" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:820 msgid "" -"For source archive and wheel references, an expected hash value may be " -"specified by including a ``=`` entry as part " -"of the URL fragment." +"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:1127 +#: ../source/specifications/version-specifiers.rst:824 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 " -"version control system with hash based commit identifiers SHOULD be used. " -"Automated tools MAY omit warnings about missing hashes for version control " -"systems that do not provide hash based commit identifiers." +"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:1133 +#: ../source/specifications/version-specifiers.rst:828 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 " -"end of the URL using the ``@`` or the ``@#`` " -"notation." +"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:1140 +#: ../source/specifications/version-specifiers.rst:833 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 " -"embedded as part of the URL. Secondly, the commit hash is included even when " -"retrieving based on a tag, in order to meet the requirement above that " -"*every* link should include a hash to make things harder to forge (creating " -"a malicious repo with a particular tag is easy, creating one with a specific " -"*hash*, less so)." +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:1148 -#, fuzzy -msgid "Remote URL examples::" -msgstr "例えば::" - -#: ../source/specifications/version-specifiers.rst:1156 +#: ../source/specifications/version-specifiers.rst:836 #, fuzzy -msgid "File URLs" -msgstr "アーカイブ URL 群" +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "次に挙げる名前はすべて同等ということになります:" -#: ../source/specifications/version-specifiers.rst:1158 +#: ../source/specifications/version-specifiers.rst:844 msgid "" -"File URLs take the form of ``file:///``. If the ```` is " -"omitted it is assumed to be ``localhost`` and even if the ```` is " -"omitted the third slash MUST still exist. The ```` defines what the " -"file path on the filesystem that is to be accessed." +"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:1163 +#: ../source/specifications/version-specifiers.rst:854 msgid "" -"On the various \\*nix operating systems the only allowed values for " -"```` is for it to be omitted, ``localhost``, or another FQDN that the " -"current machine believes matches its own host. In other words, on \\*nix the " -"``file://`` scheme can only be used to access paths on the local machine." +"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:1168 +#: ../source/specifications/version-specifiers.rst:866 +#, fuzzy +msgid "Version matching" +msgstr "バージョン指定子" + +#: ../source/specifications/version-specifiers.rst:868 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 " -"on Windows the ```` parameter may be used to specify a file residing " -"on a network share. In other words, in order to translate ``\\" -"\\machine\\volume\\file`` to a ``file://`` url, it would end up as ``file://" -"machine/volume/file``. For more information on ``file://`` URLs on Windows " -"see `MSDN `_." +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:1179 -msgid "Summary of differences from pkg_resources.parse_version" +#: ../source/specifications/version-specifiers.rst:871 +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:1181 +#: ../source/specifications/version-specifiers.rst:875 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." +"By default, the version matching operator is based on a strict equality " +"comparison: the specified version must be exactly the same as the requested " +"version. The *only* substitution performed is the zero padding of the " +"release segment to ensure the release segments are compared with the same " +"length." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:881 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." +"Whether or not strict version matching is appropriate depends on the " +"specific use case for the version specifier. Automated tools SHOULD at least " +"issue warnings and MAY reject them entirely when strict version matches are " +"used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:886 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." +"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, then trailing components " +"(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:1193 +#: ../source/specifications/version-specifiers.rst:893 +#: ../source/specifications/version-specifiers.rst:954 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." +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1202 -msgid "Appendix: Parsing version strings with regular expressions" +#: ../source/specifications/version-specifiers.rst:900 +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:1204 +#: ../source/specifications/version-specifiers.rst:908 msgid "" -"As noted earlier in the :ref:`public-version-identifiers` section, published " -"version identifiers SHOULD use the canonical format. This section provides " -"regular expressions that can be used to test whether a version is already in " -"that form, and if it's not, extract the various components for subsequent " -"normalization." +"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 " +"identifiers). Given the version ``1.1``, the following clauses would match " +"or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1210 +#: ../source/specifications/version-specifiers.rst:920 msgid "" -"To test whether a version identifier is in the canonical format, you can use " -"the following function:" +"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 " +"development release segment is always the final segment in the public " +"version, and the local version is ignored for comparison purposes, so using " +"either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:1219 +#: ../source/specifications/version-specifiers.rst:926 msgid "" -"To extract the components of a version identifier, use the following regular " -"expression (as defined by the `packaging `_ project):" +"The use of ``==`` (without at least the wildcard suffix) when defining " +"dependencies for published distributions is strongly discouraged as it " +"greatly complicates the deployment of security fixes. The strict version " +"comparison operator is intended primarily for use when defining dependencies " +"for repeatable *deployments of applications* while using a shared " +"distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:1266 -msgid "August 2014: This specification was approved through :pep:`440`." +#: ../source/specifications/version-specifiers.rst:933 +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/virtual-environments.rst:6 -msgid "Python Virtual Environments" -msgstr "Python 仮想環境" - -#: ../source/specifications/virtual-environments.rst:8 +#: ../source/specifications/version-specifiers.rst:937 msgid "" -"For Python 3.3 and later versions, :pep:`405` introduced interpreter level " -"support for the concept of \"Python Virtual Environments\". Each virtual " -"environment has its own Python binary (allowing creation of environments " -"with various Python versions) and can have its own independent set of " -"installed Python packages in its site directories, but shares the standard " -"library with the base installed Python. While the concept of virtual " -"environments existed prior to this update, there was no previously " -"standardised mechanism for declaring or discovering them." +"If the specified version identifier is a local version identifier, then the " +"local version labels of candidate versions MUST be considered when matching " +"versions, with the public version identifier being matched as described " +"above, and the local version label being checked for equivalence using a " +"strict string equality comparison." msgstr "" -"Python 3.3 およびそれ以降のバージョンでは、 :pep:`405` で \"Python 仮想環境 " -"\" の概念に対するサポートがインタープリタのレベル" -"で導入されました。それぞれの仮想環境が独自の Python バイナリを持ち (従ってさ" -"まざまなバージョンの Python 環境を作成することが可能) 、そのサイトディレクト" -"リの中にそれぞれ独立した Python パッケージ群をインストールすることができ、同" -"時に、ベースシステムにインストールされた Python と標準ライブラリを共有するこ" -"とができます。仮想環境の概念はこのアップデートに先立って存在していましたが、" -"(訳註、仮想環境を) 宣言したり発見したりするための標準化されたメカニズムはそれ" -"まで存在しなかったのです。" - -#: ../source/specifications/virtual-environments.rst:18 -msgid "Runtime detection of virtual environments" -msgstr "仮想環境のランタイムを識別する" -#: ../source/specifications/virtual-environments.rst:20 +#: ../source/specifications/version-specifiers.rst:945 #, fuzzy +msgid "Version exclusion" +msgstr "バージョン指定子" + +#: ../source/specifications/version-specifiers.rst:947 msgid "" -"At runtime, virtual environments can be identified by virtue of :py:data:" -"`sys.prefix` (the filesystem location of the running interpreter) having a " -"different value from :py:data:`sys.base_prefix` (the default filesystem " -"location of the standard library directories)." +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." msgstr "" -"ランタイムには、仮想環境は ``sys.prefix`` (動作中のインタープリタのファイルシ" -"ステム上の場所) が ``sys.base_prefix`` (標準ライブラリのディレクトリのデフォ" -"ルトでのファイルシステム上の場所) とは異なる値を持つおかげで識別可能です。" -#: ../source/specifications/virtual-environments.rst:25 +#: ../source/specifications/version-specifiers.rst:950 msgid "" -":ref:`venv-explanation` in the Python standard library documentation for " -"the :py:mod:`venv` module covers this along with the concept of " -"\"activating\" a virtual environment in an interactive operating system " -"shell (this activation step is optional and hence the changes it makes can't " -"be reliably used to detect whether a Python program is running in a virtual " -"environment or not)." +"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 "" -"Python 標準ライブラリの :py:mod:`venv` モジュールに関する説明文書の :ref:" -"`venv-explanation` は、" - -#: ../source/specifications/virtual-environments.rst:33 -msgid "Declaring installation environments as Python virtual environments" -msgstr "インストール先の環境がPython 仮想環境であることを宣言する" -#: ../source/specifications/virtual-environments.rst:35 -msgid "" -"As described in :pep:`405`, a Python virtual environment in its simplest " -"form consists of nothing more than a copy or symlink of the Python binary " -"accompanied by a ``site-packages`` directory and a ``pyvenv.cfg`` file with " -"a ``home`` key that indicates where to find the Python standard library " -"modules." +#: ../source/specifications/version-specifiers.rst:963 +msgid "Inclusive ordered comparison" msgstr "" -":pep:`405` で述べられているように、最も単純な形式での Python 仮想環境は、 " -"Python バイナリのコピーかシンボリックリンクに、 ``site-packages`` ディレクト" -"リと、 Python 標準ライブラリのモジュール群がどこで見つかるかを指し示す " -"``home`` キーを伴った ``pyvenv.cfg`` ファイルが随伴しているだけのもので構成さ" -"れます。" -#: ../source/specifications/virtual-environments.rst:40 +#: ../source/specifications/version-specifiers.rst:965 msgid "" -"While designed to meet the needs of the standard :py:mod:`venv` module, this " -"split installation and ``pyvenv.cfg`` file approach can be used by *any* " -"Python installation provider that desires Python-specific tools to be aware " -"that they are already operating in a virtual environment and no further " -"environment nesting is required or desired." +"An inclusive ordered comparison clause includes a comparison operator and a " +"version identifier, and will match any version where the comparison is " +"correct based on the relative position of the candidate version and the " +"specified version given the consistent ordering defined by the standard " +"`Version scheme`_." msgstr "" -"標準である :py:mod:`venv` モジュールの要求するものに合うように設計されている" -"一方で、この分割実装と ``pyvenv.cfg`` ファイルのアプローチは、Python に特化し" -"たツール群が自身がすでに仮想環境の中で動作していて、それ以上の入れ子環境は要" -"求もされておらず望ましくもないことを認識するようにしたいと望む Python 実装提" -"供者なら *誰でも* 採用することができます。" -#: ../source/specifications/virtual-environments.rst:46 -#, fuzzy +#: ../source/specifications/version-specifiers.rst:971 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:973 +#: ../source/specifications/version-specifiers.rst:1003 msgid "" -"Even in the absence of a ``pyvenv.cfg`` file, any approach (e.g. " -"``sitecustomize.py``, patching the installed Python runtime) that results " -"in :py:data:`sys.prefix` and :py:data:`sys.base_prefix` having different " -"values, while still providing a matching default package installation scheme " -"in :py:mod:`sysconfig`, will be detected and behave as a Python virtual " -"environment." +"As with version matching, the release segment is zero padded as necessary to " +"ensure the release segments are compared with the same length." msgstr "" -"``pyvenv.cfg`` ファイルがない場合であっても、 ``sys.prefix`` と ``sys." -"base_prefix`` が相異なる値を持つような結果となる一方で以前として対応するパッ" -"ケージ実装スキームを ``sysconfig`` 内で提供するアプローチ (例えば Python ラン" -"タイムにパッチを当てる ``sitecustomize.py``) であればどれでも、それと認識され" -"て Python 仮想環境として振る舞います。" -#: ../source/specifications/virtual-environments.rst:56 -msgid "May 2012: This specification was approved through :pep:`405`." +#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:1006 +msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/support.rst:3 -msgid "How to Get Support" -msgstr "サポートを得るには" +#: ../source/specifications/version-specifiers.rst:980 +msgid "Exclusive ordered comparison" +msgstr "" -#: ../source/support.rst:5 +#: ../source/specifications/version-specifiers.rst:982 msgid "" -"For support related to a specific project, see the links on the :doc:" -"`Projects ` page." +"The exclusive ordered comparisons ``>`` and ``<`` are similar to the " +"inclusive ordered comparisons in that they rely on the relative position of " +"the candidate version and the specified version given the consistent " +"ordering defined by the standard `Version scheme`_. However, they " +"specifically exclude pre-releases, post-releases, and local versions of the " +"specified version." msgstr "" -"特定のプロジェクトに関係するサポートについては、 :doc:`プロジェクト群 " -"` のリンク集のページを見てください。" -#: ../source/support.rst:8 +#: ../source/specifications/version-specifiers.rst:988 msgid "" -"For something more general, or when you're just not sure, please `open an " -"issue `_ on the `packaging-problems `_ repository on GitHub." +"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 " +"that releases are later than a particular post release, including additional " +"post releases, by using ``>V.postN``. For example, ``>1.7`` will allow " +"``1.7.1`` but not ``1.7.0.post1`` and ``>1.7.post2`` will allow ``1.7.1`` " +"and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -"もっと一般的なサポートを求めている場合や、確信を持てないだけの場合には、" -"GitHub の `パッケージングに関わる問題 `_ の `課題リストに課題を作成する `_ 下さい。" - -#: ../source/tutorials/creating-documentation.rst:4 -#, fuzzy -msgid "Creating documentation" -msgstr "説明文書を作成する" -#: ../source/tutorials/creating-documentation.rst:6 +#: ../source/specifications/version-specifiers.rst:995 msgid "" -"This tutorial has been removed since it is not related to packaging and was " -"unmaintained. Please see the `Sphinx tutorial `_ instead." +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." msgstr "" -#: ../source/tutorials/index.rst:4 +#: ../source/specifications/version-specifiers.rst:998 msgid "" -"**Tutorials** are opinionated step-by-step guides to help you get familiar " -"with packaging concepts. For more detailed information on specific packaging " -"topics, see :doc:`/guides/index`." +"The exclusive ordered comparison ```." +"Arbitrary equality comparisons are simple string equality operations which " +"do not take into account any of the semantic information such as zero " +"padding or local versions. This operator also does not support prefix " +"matching as the ``==`` operator does." msgstr "" -"この節では、 Python の :term:`パッケージ ` をインストー" -"ルする方法の基本について示します。" -#: ../source/tutorials/installing-packages.rst:10 -#, fuzzy +#: ../source/specifications/version-specifiers.rst:1017 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 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." +"The primary use case for arbitrary equality is to allow for specifying a " +"version which cannot otherwise be represented by this specification. This " +"operator is special and acts as an escape hatch to allow someone using a " +"tool which implements this specification to still install a legacy version " +"which is otherwise incompatible with this specification." msgstr "" -"この文脈では、 \"パッケージ\" という用語が、インストールされるソフトウェアの" -"束を表すものである (すなわち、 :term:`配布物 ` の同義語" -"である) ことを注記しておくことは重要です。 Python のなんらかのソースコードを" -"インポートする (つまり、モジュール群の) 容れ物としての :term:`パッケージ " -"` のことを指してはいないのです。 Python のコミュニティで" -"は、 :term:`配布物 ` のことを \"パッケージ\" という用語" -"で呼ぶことは一般的に行われています。 Linux ディストロや、 Python そのもののよ" -"うなその他の大きなソフトウェア配布物と紛らわしいので、 \"配布物\" という用語" -"を使うことはしばしば歓迎されません。" - -#: ../source/tutorials/installing-packages.rst:24 -msgid "Requirements for Installing Packages" -msgstr "パッケージをインストールするための必須事項" -#: ../source/tutorials/installing-packages.rst:26 +#: ../source/specifications/version-specifiers.rst:1023 msgid "" -"This section describes the steps to follow before installing other Python " -"packages." +"An example would be ``===foobar`` which would match a version of ``foobar``." msgstr "" -"この節では、その他の Python パッケージをインストールする前にやっておくべきス" -"テップを記します。" -#: ../source/tutorials/installing-packages.rst:31 -msgid "Ensure you can run Python from the command line" -msgstr "コマンドラインから Python を起動できることを確認する" - -#: ../source/tutorials/installing-packages.rst:33 +#: ../source/specifications/version-specifiers.rst:1025 msgid "" -"Before you go any further, make sure you have Python and that the expected " -"version is available from your command line. You can check this by running:" +"This operator may also be used to explicitly require an unpatched version of " +"a project such as ``===1.0`` which would not match for a version " +"``1.0+downstream1``." msgstr "" -"先へ進む前に、期待通りのバージョンの Python が手元のコマンドラインで動作して" -"いることを確認しておきましょう。つぎのコマンドを実行すれば確認できます:" -#: ../source/tutorials/installing-packages.rst:49 +#: ../source/specifications/version-specifiers.rst:1029 msgid "" -"You should get some output like ``Python 3.6.3``. If you do not have Python, " -"please install the latest 3.x version from `python.org`_ or refer to the :" -"ref:`Installing Python ` section of the " -"Hitchhiker's Guide to Python." +"Use of this operator is heavily discouraged and tooling MAY display a " +"warning when it is used." msgstr "" -"``Python 3.6.3`` のような応答が出力されるはずです。もし Python がなければ、最" -"新バージョンの 3.x を `python.org`_ からインストールするか、 Python ユーザの" -"ためのヒッチハイクガイドの :ref:`Python をインストールする ` の節を参照するか、どちらかをしてください。" -#: ../source/tutorials/installing-packages.rst:53 -msgid "If you're a newcomer and you get an error like this:" -msgstr "あなたがまだ慣れていなくて、しかも次のようなエラーに遭遇した場合には:" +#: ../source/specifications/version-specifiers.rst:1034 +#, fuzzy +msgid "Handling of pre-releases" +msgstr "リリース前のバージョンをインストールする" -#: ../source/tutorials/installing-packages.rst:62 +#: ../source/specifications/version-specifiers.rst:1036 msgid "" -"It's because this command and other suggested commands in this tutorial are " -"intended to be run in a *shell* (also called a *terminal* or *console*). See " -"the Python for Beginners `getting started tutorial`_ for an introduction to " -"using your operating system's shell and interacting with Python." +"Pre-releases of any kind, including developmental releases, are implicitly " +"excluded from all version specifiers, *unless* they are already present on " +"the system, explicitly requested by the user, or if the only available " +"version that satisfies the version specifier is a pre-release." msgstr "" -"それは、このコマンドや、このチュートリアルに出てくる他のコマンドが、 *シェル" -"* (*ターミナル* とか *コンソール* とも呼ばれます) で動作することを意図してい" -"るからです。オペレーティングシステムのシェルを使って Python とやりとりするた" -"めの導入説明として、初心者のための Python `はじめの第一歩チュートリアル " -"`_ [1]_" +"``== 3.1``: specifically version 3.1 (or 3.1.0), excludes all pre-releases, " +"post releases, developmental releases and any 3.1.x maintenance releases." msgstr "" -"`get-pip.py `_ [1]_ をセキュアにダウン" -"ロードする" -#: ../source/tutorials/installing-packages.rst:139 +#: ../source/specifications/version-specifiers.rst:1074 msgid "" -"Run ``python get-pip.py``. [2]_ This will install or upgrade pip. " -"Additionally, it will install :ref:`setuptools` and :ref:`wheel` if they're " -"not installed already." +"``== 3.1.*``: any version that starts with 3.1. Equivalent to the " +"``~=3.1.0`` compatible release clause." msgstr "" -"``python get-pip.py`` を実行してください [2]_ 。これで pip をインストールまた" -"は更新することができます。さらに、まだインストールされていなければ、 :ref:" -"`setuptools` と :ref:`wheel` もインストールされるでしょう。" -#: ../source/tutorials/installing-packages.rst:145 +#: ../source/specifications/version-specifiers.rst:1076 msgid "" -"Be cautious if you're using a Python install that's managed by your " -"operating system or another package manager. get-pip.py does not coordinate " -"with those tools, and may leave your system in an inconsistent state. You " -"can use ``python get-pip.py --prefix=/usr/local/`` to install in ``/usr/" -"local`` which is designed for locally-installed software." +"``~=3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3 and not " +"version 3.2.0 or later." msgstr "" -"オペレーティングシステムないし他のパッケージ管理機構を使ってインストールした " -"Python を管理しているなら、用心深くあるべきです。 get-pip.py はそのようなツー" -"ル群と協調して動作する訳ではないので、あなたのシステムの一貫性を破壊するかも" -"しれません。ソフトウェアをローカルにインストールするために設計された ``/usr/" -"local`` にインストールするなら ``python get-pip.py --prefix=/usr/local`` を使" -"うことができます。" -#: ../source/tutorials/installing-packages.rst:154 -msgid "Ensure pip, setuptools, and wheel are up to date" -msgstr "pip ・ setuptools ・ wheel が最新版であることを確実にする" +#: ../source/specifications/version-specifiers.rst:1081 +#, fuzzy +msgid "Direct references" +msgstr "参考文献" -#: ../source/tutorials/installing-packages.rst:156 +#: ../source/specifications/version-specifiers.rst:1083 msgid "" -"While ``pip`` alone is sufficient to install from pre-built binary archives, " -"up to date copies of the ``setuptools`` and ``wheel`` projects are useful to " -"ensure you can also install from source archives:" +"Some automated tools may permit the use of a direct reference as an " +"alternative to a normal version specifier. A direct reference consists of " +"the specifier ``@`` and an explicit URL." msgstr "" -"``pip`` 単体でも事前にビルドされたバイナリアーカイブからインストールを行うに" -"は十分ですが、最新の ``setuptools`` と ``wheel`` があればソースコードアーカイ" -"ブからでも確実にインストールすることができるので便利です:" -#: ../source/tutorials/installing-packages.rst:173 -msgid "Optionally, create a virtual environment" -msgstr "必須ではないが、仮想環境を構築する" +#: ../source/specifications/version-specifiers.rst:1087 +msgid "" +"Whether or not direct references are appropriate depends on the specific use " +"case for the version specifier. Automated tools SHOULD at least issue " +"warnings and MAY reject them entirely when direct references are used " +"inappropriately." +msgstr "" -#: ../source/tutorials/installing-packages.rst:175 +#: ../source/specifications/version-specifiers.rst:1092 msgid "" -"See :ref:`section below ` for " -"details, but here's the basic :doc:`venv ` [3]_ command " -"to use on a typical Linux system:" +"Public index servers SHOULD NOT allow the use of direct references in " +"uploaded distributions. Direct references are intended as a tool for " +"software integrators rather than publishers." msgstr "" -"詳しいことは、 :ref:`下の節 ` に出て" -"いますので、ここでは基本的な :doc:`venv ` [3]_ コマンド" -"を典型的な Linux システムで使うやり方を説明します:" -#: ../source/tutorials/installing-packages.rst:192 +#: ../source/specifications/version-specifiers.rst:1096 msgid "" -"This will create a new virtual environment in the ``tutorial_env`` " -"subdirectory, and configure the current shell to use it as the default " -"``python`` environment." +"Depending on the use case, some appropriate targets for a direct URL " +"reference may be an sdist or a wheel binary archive. The exact URLs and " +"targets supported will be tool dependent." msgstr "" -"これで新しい仮想環境が ``tutorial_env`` サブディレクトリ内に生成され、それを" -"現在のシェルのデフォルトの ``python`` 環境として使わせることができます。" -#: ../source/tutorials/installing-packages.rst:199 -msgid "Creating Virtual Environments" -msgstr "仮想環境を構築する" +#: ../source/specifications/version-specifiers.rst:1100 +msgid "For example, a local source archive may be referenced directly::" +msgstr "" -#: ../source/tutorials/installing-packages.rst:201 -msgid "" -"Python \"Virtual Environments\" allow Python :term:`packages ` to be installed in an isolated location for a particular " -"application, rather than being installed globally. If you are looking to " -"safely install global command line tools, see :doc:`/guides/installing-stand-" -"alone-command-line-tools`." +#: ../source/specifications/version-specifiers.rst:1104 +msgid "Alternatively, a prebuilt archive may also be referenced::" msgstr "" -"Python の \"仮想環境\" を使えば、 Python の :term:`パッケージ ` をグローバルな環境にインストールする代わりに、特定のアプリケーショ" -"ンのための隔離された場所にインストールすることができます。グローバルなコマン" -"ドラインツールを安全にインストールしたいのであれば、 :doc:`/guides/" -"installing-stand-aline-command-line-tools` を見てください。" -#: ../source/tutorials/installing-packages.rst:207 +#: ../source/specifications/version-specifiers.rst:1108 msgid "" -"Imagine you have an application that needs version 1 of LibFoo, but another " -"application requires version 2. How can you use both these applications? If " -"you install everything into /usr/lib/python3.6/site-packages (or whatever " -"your platform’s standard location is), it’s easy to end up in a situation " -"where you unintentionally upgrade an application that shouldn’t be upgraded." +"All direct references that do not refer to a local file URL SHOULD specify a " +"secure transport mechanism (such as ``https``) AND include an expected hash " +"value in the URL for verification purposes. If a direct reference is " +"specified without any hash information, with hash information that the tool " +"doesn't understand, or with a selected hash algorithm that the tool " +"considers too weak to trust, automated tools SHOULD at least emit a warning " +"and MAY refuse to rely on the URL. If such a direct reference also uses an " +"insecure transport, automated tools SHOULD NOT rely on the URL." msgstr "" -"手持ちのあるアプリケーションには LibFoo のバージョン 1 が必要で、しかし、別の" -"アプリケーションではバージョン 2 を要求していると想像してみてください。このよ" -"うなアプリケーションを両方同時に使うためにはどうすれば良いでしょうか？あらゆ" -"るものを /usr/lib/python3.6/site-packages (または、あなたが使っているプラット" -"フォームの標準的な置き場所ならどこでも) にインストールするとすれば、容易く、" -"アップグレードするべきでないはずのアプリケーションを意図せずアップグレードし" -"てしまう結果に終わるでしょう。" -#: ../source/tutorials/installing-packages.rst:213 +#: ../source/specifications/version-specifiers.rst:1117 +#, fuzzy msgid "" -"Or more generally, what if you want to install an application and leave it " -"be? If an application works, any change in its libraries or the versions of " -"those libraries can break the application." +"It is RECOMMENDED that only hashes which are unconditionally provided by the " +"latest version of the standard library's :py:mod:`hashlib` module be used " +"for source archive hashes. At time of writing, that list consists of " +"``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and " +"``'sha512'``." msgstr "" -"あるいは、もっと一般的には、あるアプリケーションをインストールして、そのまま" -"にしておきたいとすればどうでしょう？アプリケーションが動作したとしても、ライ" -"ブラリへの何らかの変更や、ライブラリのバージョン問題でアプリケーションが動作" -"しなくなってしまうかもしれません。" +"``hash`` キー (``string`` 型) は、 ``=`` とい" +"う値を伴ってソンゾンしているべきです。標準ライブラリの ``hash lib`` モジュー" +"ルの最新版が無条件に提供するハッシュだけをソースコードアーカイブのハッシュと" +"して使うことを推奨します。本文書の執筆時点では、 'md5' ・ 'sha1' ・ 'sha224' " +"・ 'sha256' ・ 'sha384' ・ 'sha512' が該当します。" -#: ../source/tutorials/installing-packages.rst:217 +#: ../source/specifications/version-specifiers.rst:1123 msgid "" -"Also, what if you can’t install :term:`packages ` into " -"the global site-packages directory? For instance, on a shared host." +"For source archive and wheel references, an expected hash value may be " +"specified by including a ``=`` entry as part " +"of the URL fragment." msgstr "" -"あるいは、グローバルな site-packages ディレクトリに :term:`パッケージ " -"` をインストールすることができないとしたら、どうでしょ" -"うか？例えば、共有ホストのような。" -#: ../source/tutorials/installing-packages.rst:220 +#: ../source/specifications/version-specifiers.rst:1127 msgid "" -"In all these cases, virtual environments can help you. They have their own " -"installation directories and they don’t share libraries with other virtual " -"environments." +"For version control references, the ``VCS+protocol`` scheme SHOULD be used " +"to identify both the version control system and the secure transport, and a " +"version control system with hash based commit identifiers SHOULD be used. " +"Automated tools MAY omit warnings about missing hashes for version control " +"systems that do not provide hash based commit identifiers." msgstr "" -"このようなすべての場合において、仮想環境はあなたを助けることができます。仮想" -"環境にはそれぞれのインストール先ディレクトリが別にあって、他の仮想環境とライ" -"ブラリを共有するということがないからです。" -#: ../source/tutorials/installing-packages.rst:224 +#: ../source/specifications/version-specifiers.rst:1133 msgid "" -"Currently, there are two common tools for creating Python virtual " -"environments:" +"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 " +"end of the URL using the ``@`` or the ``@#`` " +"notation." msgstr "" -"現在、ふたつの Python 仮想環境を構築するためのツールがよく知られています:" -#: ../source/tutorials/installing-packages.rst:226 +#: ../source/specifications/version-specifiers.rst:1140 msgid "" -":doc:`venv ` is available by default in Python 3.3 and " -"later, and installs :ref:`pip` and :ref:`setuptools` into created virtual " -"environments in Python 3.4 and later." +"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 " +"embedded as part of the URL. Secondly, the commit hash is included even when " +"retrieving based on a tag, in order to meet the requirement above that " +"*every* link should include a hash to make things harder to forge (creating " +"a malicious repo with a particular tag is easy, creating one with a specific " +"*hash*, less so)." msgstr "" -":doc:`venv ` は、 Python 3.3 およびそれ以降のバージョン" -"で本体に同梱されていて利用可能であり、 Python 3.4 およびそれ以降では (venv" -"が) :ref:`pip` と :ref:`setuptools` を作成された仮想環境内にインストールしま" -"す。" -#: ../source/tutorials/installing-packages.rst:229 +#: ../source/specifications/version-specifiers.rst:1148 +#, fuzzy +msgid "Remote URL examples::" +msgstr "例えば::" + +#: ../source/specifications/version-specifiers.rst:1156 +#, fuzzy +msgid "File URLs" +msgstr "アーカイブ URL 群" + +#: ../source/specifications/version-specifiers.rst:1158 msgid "" -":ref:`virtualenv` needs to be installed separately, but supports Python 2.7+ " -"and Python 3.3+, and :ref:`pip`, :ref:`setuptools` and :ref:`wheel` are " -"always installed into created virtual environments by default (regardless of " -"Python version)." +"File URLs take the form of ``file:///``. If the ```` is " +"omitted it is assumed to be ``localhost`` and even if the ```` is " +"omitted the third slash MUST still exist. The ```` defines what the " +"file path on the filesystem that is to be accessed." msgstr "" -":ref:`virtualenv` は別途インストールする必要がありますが、 Python 2.7+ と " -"Python 3.3+ をサポートしており、 :ref:`pip` ・ :ref:`setuptools` ・ :ref:" -"`wheel` を作成された仮想環境に常にデフォルト (Python のバージョンに関係なく) " -"でインストールします。" -#: ../source/tutorials/installing-packages.rst:234 -msgid "The basic usage is like so:" -msgstr "基本的な使い方は次の通りです:" +#: ../source/specifications/version-specifiers.rst:1163 +msgid "" +"On the various \\*nix operating systems the only allowed values for " +"```` is for it to be omitted, ``localhost``, or another FQDN that the " +"current machine believes matches its own host. In other words, on \\*nix the " +"``file://`` scheme can only be used to access paths on the local machine." +msgstr "" -#: ../source/tutorials/installing-packages.rst:236 -msgid "Using :doc:`venv `:" -msgstr ":doc:`venv ` を使うと:" +#: ../source/specifications/version-specifiers.rst:1168 +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 " +"on Windows the ```` parameter may be used to specify a file residing " +"on a network share. In other words, in order to translate ``\\" +"\\machine\\volume\\file`` to a ``file://`` url, it would end up as ``file://" +"machine/volume/file``. For more information on ``file://`` URLs on Windows " +"see `MSDN `_." +msgstr "" -#: ../source/tutorials/installing-packages.rst:252 -msgid "Using :ref:`virtualenv`:" -msgstr ":ref:`virtualenv` を使うと:" +#: ../source/specifications/version-specifiers.rst:1179 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" -#: ../source/tutorials/installing-packages.rst:268 +#: ../source/specifications/version-specifiers.rst:1181 msgid "" -"For more information, see the :doc:`venv ` docs or the :" -"doc:`virtualenv ` docs." +"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 "" -"さらなる説明は、 :doc:`venv ` の説明文書や :doc:" -"`virtualenv ` の説明文書をみてください。" -#: ../source/tutorials/installing-packages.rst:271 +#: ../source/specifications/version-specifiers.rst:1185 msgid "" -"The use of :command:`source` under Unix shells ensures that the virtual " -"environment's variables are set within the current shell, and not in a " -"subprocess (which then disappears, having no useful effect)." +"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 "" -"UNIX のシェル上で :command:`source` を使うとそのシェル内では仮想環境用の変数" -"が設定されますが、サブシェルでは設定され (ず、役に立つ効果が残り) ません。" -#: ../source/tutorials/installing-packages.rst:276 -#, fuzzy +#: ../source/specifications/version-specifiers.rst:1189 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:" +"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 "" -"上記のいずれの場合でも、 Windows ユーザは :command:`source` コマンドを使うべ" -"きではあなく、代わりに :command:`activate` スクリプトをコマンドシェルから直接" -"に実行するべきで、例えば次のようにします:" -#: ../source/tutorials/installing-packages.rst:286 +#: ../source/specifications/version-specifiers.rst:1193 msgid "" -"Managing multiple virtual environments directly can become tedious, so the :" -"ref:`dependency management tutorial ` introduces a " -"higher level tool, :ref:`Pipenv`, that automatically manages a separate " -"virtual environment for each project and application that you work on." +"``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 "" -"複数の仮想環境をそのままで管理することはうんざりする作業になりがちなので、 :" -"ref:`依存関係を管理するためのチュートリアル ` では、よ" -"り抽象度の高いツール :ref:`Pipenv` を使ってプロジェクトやアプリケーションのそ" -"れぞれのために作成した個別の仮想環境群を自動的に管理する方法を紹介していま" -"す。" -#: ../source/tutorials/installing-packages.rst:293 -msgid "Use pip for Installing" -msgstr "pip を使ってインストールする" +#: ../source/specifications/version-specifiers.rst:1202 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" -#: ../source/tutorials/installing-packages.rst:295 +#: ../source/specifications/version-specifiers.rst:1204 msgid "" -":ref:`pip` is the recommended installer. Below, we'll cover the most common " -"usage scenarios. For more detail, see the :doc:`pip docs `, which " -"includes a complete :doc:`Reference Guide `." +"As noted earlier in the :ref:`public-version-identifiers` section, published " +"version identifiers SHOULD use the canonical format. This section provides " +"regular expressions that can be used to test whether a version is already in " +"that form, and if it's not, extract the various components for subsequent " +"normalization." msgstr "" -":ref:`pip` は推奨されているインストーラです。以下に最もよくある使用シナリオを" -"挙げます。より詳しくは、 :doc:`リファレンスガイド ` の全体を含" -"む :doc:`pip 説明文書 ` を見てください。" -#: ../source/tutorials/installing-packages.rst:301 -msgid "Installing from PyPI" -msgstr "PyPI からインストールする" +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" -#: ../source/tutorials/installing-packages.rst:303 -#, fuzzy +#: ../source/specifications/version-specifiers.rst:1219 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 `. A full description of the " -"supported specifiers can be found in the :ref:`Version specifier " -"specification `. Below are some examples." +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" msgstr "" -":ref:`pip` の最もよくある使い方は、 :term:`要求事項指定子 ` を用いて :term:`Python パッケージインデックス ` からインストールすることです。一般的には、要求事項識別子は、プ" -"ロジェクト名と後続する省略可能な :term:`バージョン指定子 ` で構成されています。 :pep:`440` に、現在サポートされている識別子" -"の :pep:`完全な仕様 <440#version-specifiers>` があります。以下にいくつかの例" -"を挙げます。" -#: ../source/tutorials/installing-packages.rst:311 -msgid "To install the latest version of \"SomeProject\":" -msgstr "\"とあるプロジェクト\" の最新版をインストールするには:" +#: ../source/specifications/version-specifiers.rst:1266 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" -#: ../source/tutorials/installing-packages.rst:325 -msgid "To install a specific version:" -msgstr "特定のバージョンをインストールするには:" +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "Python 仮想環境" -#: ../source/tutorials/installing-packages.rst:339 -msgid "To install greater than or equal to one version and less than another:" +#: ../source/specifications/virtual-environments.rst:8 +msgid "" +"For Python 3.3 and later versions, :pep:`405` introduced interpreter level " +"support for the concept of \"Python Virtual Environments\". Each virtual " +"environment has its own Python binary (allowing creation of environments " +"with various Python versions) and can have its own independent set of " +"installed Python packages in its site directories, but shares the standard " +"library with the base installed Python. While the concept of virtual " +"environments existed prior to this update, there was no previously " +"standardised mechanism for declaring or discovering them." msgstr "" -"あるバージョンと同じか新しいバージョンで、もう一つのものより古いものをインス" -"トールするには:" +"Python 3.3 およびそれ以降のバージョンでは、 :pep:`405` で \"Python 仮想環境 " +"\" の概念に対するサポートがインタープリタのレベル" +"で導入されました。それぞれの仮想環境が独自の Python バイナリを持ち (従ってさ" +"まざまなバージョンの Python 環境を作成することが可能) 、そのサイトディレクト" +"リの中にそれぞれ独立した Python パッケージ群をインストールすることができ、同" +"時に、ベースシステムにインストールされた Python と標準ライブラリを共有するこ" +"とができます。仮想環境の概念はこのアップデートに先立って存在していましたが、" +"(訳註、仮想環境を) 宣言したり発見したりするための標準化されたメカニズムはそれ" +"まで存在しなかったのです。" -#: ../source/tutorials/installing-packages.rst:354 +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "仮想環境のランタイムを識別する" + +#: ../source/specifications/virtual-environments.rst:20 #, fuzzy msgid "" -"To install a version that's :ref:`compatible ` with a certain version: [4]_" +"At runtime, virtual environments can be identified by virtue of :py:data:" +"`sys.prefix` (the filesystem location of the running interpreter) having a " +"different value from :py:data:`sys.base_prefix` (the default filesystem " +"location of the standard library directories)." msgstr "" -"あるバージョンと :pep:`\"互換性がある\" <440#compatible-release>` バージョン" -"をインストールするには: [4]_" +"ランタイムには、仮想環境は ``sys.prefix`` (動作中のインタープリタのファイルシ" +"ステム上の場所) が ``sys.base_prefix`` (標準ライブラリのディレクトリのデフォ" +"ルトでのファイルシステム上の場所) とは異なる値を持つおかげで識別可能です。" -#: ../source/tutorials/installing-packages.rst:369 +#: ../source/specifications/virtual-environments.rst:25 msgid "" -"In this case, this means to install any version \"==1.4.*\" version that's " -"also \">=1.4.2\"." +":ref:`venv-explanation` in the Python standard library documentation for " +"the :py:mod:`venv` module covers this along with the concept of " +"\"activating\" a virtual environment in an interactive operating system " +"shell (this activation step is optional and hence the changes it makes can't " +"be reliably used to detect whether a Python program is running in a virtual " +"environment or not)." msgstr "" -"この場合には、 \"==1.4.*\" で、かつ、 \">=1.4.2\" であるバージョンをインス" -"トールするという意味になります。" +"Python 標準ライブラリの :py:mod:`venv` モジュールに関する説明文書の :ref:" +"`venv-explanation` は、" -#: ../source/tutorials/installing-packages.rst:374 -msgid "Source Distributions vs Wheels" -msgstr "ソースコード配布物 vs. Wheels" +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "インストール先の環境がPython 仮想環境であることを宣言する" -#: ../source/tutorials/installing-packages.rst:376 +#: ../source/specifications/virtual-environments.rst:35 msgid "" -":ref:`pip` can install from either :term:`Source Distributions (sdist) " -"` or :term:`Wheels `, but if both " -"are present on PyPI, pip will prefer a compatible :term:`wheel `. You " -"can override pip`s default behavior by e.g. using its :ref:`--no-binary ` option." +"As described in :pep:`405`, a Python virtual environment in its simplest " +"form consists of nothing more than a copy or symlink of the Python binary " +"accompanied by a ``site-packages`` directory and a ``pyvenv.cfg`` file with " +"a ``home`` key that indicates where to find the Python standard library " +"modules." msgstr "" -":ref:`pip` は、 :term:`ソースコード配布物 (sdist) ` または :term:`Wheels ` のどちらからでもインストールするこ" -"とができますが、両方が PyPI に存在している場合には pip は互換性のある :term:" -"`wheel ` を選好します。例えば :ref:`--no-binary ` オプションを使うことで pip のデフォルト動作を上書き修正することがで" -"きます。" +":pep:`405` で述べられているように、最も単純な形式での Python 仮想環境は、 " +"Python バイナリのコピーかシンボリックリンクに、 ``site-packages`` ディレクト" +"リと、 Python 標準ライブラリのモジュール群がどこで見つかるかを指し示す " +"``home`` キーを伴った ``pyvenv.cfg`` ファイルが随伴しているだけのもので構成さ" +"れます。" -#: ../source/tutorials/installing-packages.rst:382 +#: ../source/specifications/virtual-environments.rst:40 msgid "" -":term:`Wheels ` are a pre-built :term:`distribution ` format that provides faster installation compared to :term:`Source " -"Distributions (sdist) `, especially when " -"a project contains compiled extensions." +"While designed to meet the needs of the standard :py:mod:`venv` module, this " +"split installation and ``pyvenv.cfg`` file approach can be used by *any* " +"Python installation provider that desires Python-specific tools to be aware " +"that they are already operating in a virtual environment and no further " +"environment nesting is required or desired." msgstr "" -":term:`Wheels ` は、ビルド済みの :term:`配布物 ` フォーマットで、特にプロジェクトがコンパイル済み拡張を含んでいる場" -"合には、 :term:`ソースコード配布物 (sdist) ` に比べてより短時間でインストールすることができます。" +"標準である :py:mod:`venv` モジュールの要求するものに合うように設計されている" +"一方で、この分割実装と ``pyvenv.cfg`` ファイルのアプローチは、Python に特化し" +"たツール群が自身がすでに仮想環境の中で動作していて、それ以上の入れ子環境は要" +"求もされておらず望ましくもないことを認識するようにしたいと望む Python 実装提" +"供者なら *誰でも* 採用することができます。" -#: ../source/tutorials/installing-packages.rst:387 +#: ../source/specifications/virtual-environments.rst:46 +#, fuzzy msgid "" -"If :ref:`pip` does not find a wheel to install, it will locally build a " -"wheel and cache it for future installs, instead of rebuilding the source " -"distribution in the future." +"Even in the absence of a ``pyvenv.cfg`` file, any approach (e.g. " +"``sitecustomize.py``, patching the installed Python runtime) that results " +"in :py:data:`sys.prefix` and :py:data:`sys.base_prefix` having different " +"values, while still providing a matching default package installation scheme " +"in :py:mod:`sysconfig`, will be detected and behave as a Python virtual " +"environment." msgstr "" -":ref:`pip` がインストールするべき wheel を発見できなかった場合には、手元で " -"wheel をビルドして、将来のインストール時に再びソースコード配布物からリビルド" -"しないで済むようにキャッシュしておきます。" - -#: ../source/tutorials/installing-packages.rst:395 -msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +"``pyvenv.cfg`` ファイルがない場合であっても、 ``sys.prefix`` と ``sys." +"base_prefix`` が相異なる値を持つような結果となる一方で以前として対応するパッ" +"ケージ実装スキームを ``sysconfig`` 内で提供するアプローチ (例えば Python ラン" +"タイムにパッチを当てる ``sitecustomize.py``) であればどれでも、それと認識され" +"て Python 仮想環境として振る舞います。" + +#: ../source/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." msgstr "" -"インストール済みの ``とあるプロジェクト`` を PyPI から最新版に更新する。" -#: ../source/tutorials/installing-packages.rst:412 -msgid "Installing to the User Site" -msgstr "ユーザサイトへインストールする" +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "サポートを得るには" -#: ../source/tutorials/installing-packages.rst:414 +#: ../source/support.rst:5 msgid "" -"To install :term:`packages ` that are isolated to the " -"current user, use the ``--user`` flag:" +"For support related to a specific project, see the links on the :doc:" +"`Projects ` page." msgstr "" -":term:`パッケージ ` を現在のユーザだけが使えるように他" -"から隔離してインストールするには ``--user`` フラグを使います:" +"特定のプロジェクトに関係するサポートについては、 :doc:`プロジェクト群 " +"` のリンク集のページを見てください。" -#: ../source/tutorials/installing-packages.rst:429 +#: ../source/support.rst:8 msgid "" -"For more information see the `User Installs `_ section from the pip docs." +"For something more general, or when you're just not sure, please `open an " +"issue `_ on the `packaging-problems `_ repository on GitHub." msgstr "" -"もっと詳しい情報を知りたければ、pip 説明文書の `ユーザ限定のインストール " -"`_ の節を見てくださ" -"い。" +"もっと一般的なサポートを求めている場合や、確信を持てないだけの場合には、" +"GitHub の `パッケージングに関わる問題 `_ の `課題リストに課題を作成する `_ 下さい。" -#: ../source/tutorials/installing-packages.rst:433 +#: ../source/tutorials/creating-documentation.rst:4 +#, fuzzy +msgid "Creating documentation" +msgstr "説明文書を作成する" + +#: ../source/tutorials/creating-documentation.rst:6 msgid "" -"Note that the ``--user`` flag has no effect when inside a virtual " -"environment - all installation commands will affect the virtual environment." +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." msgstr "" -"仮想環境の中では ``--user`` フラグが無効になることに注意してください - すべて" -"のインストールコマンドが仮想環境に影響を与えます。" -#: ../source/tutorials/installing-packages.rst:436 +#: ../source/tutorials/index.rst:4 msgid "" -"If ``SomeProject`` defines any command-line scripts or console entry points, " -"``--user`` will cause them to be installed inside the `user base`_'s binary " -"directory, which may or may not already be present in your shell's :envvar:" -"`PATH`. (Starting in version 10, pip displays a warning when installing any " -"scripts to a directory outside :envvar:`PATH`.) If the scripts are not " -"available in your shell after installation, you'll need to add the directory " -"to your :envvar:`PATH`:" +"**Tutorials** are opinionated step-by-step guides to help you get familiar " +"with packaging concepts. For more detailed information on specific packaging " +"topics, see :doc:`/guides/index`." msgstr "" -"``とあるプロジェクト`` がコマンドラインスクリプトかコンソールエントリポイント" -"をひとつでも定義しているのであれば、 ``--user`` を与えることで 、 `ユーザベー" -"ス `_ のバイナリ置き場、それがシェルの :envvar:`PATH` 変数にあろう" -"がなかろうが、そこにインストールすることになるでしょう (バージョン 10 以降の " -"pip では、スクリプトを :envvar:`PATH` に含まれていないパスにインストールする" -"時には警告を表示します)。インストール後にスクリプトが利用可能でない場合に" -"は、 :envvar:`PATH` にそのディレクトリパスを追加する必要があるでしょう:" +"**チュートリアル** は、どのようにすれば良いかを指示しながらステップバイステッ" +"プで進めるガイドで、あなたがパッケージングの概念に慣れ親しむのを助けます。" +"パッケージングの特定の話題に関するより詳しい情報については、 :doc:`/guides/" +"index` を見てください。" -#: ../source/tutorials/installing-packages.rst:444 +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "パッケージをインストールする" + +#: ../source/tutorials/installing-packages.rst:7 msgid "" -"On Linux and macOS you can find the user base binary directory by running " -"``python -m site --user-base`` and adding ``bin`` to the end. For example, " -"this will typically print ``~/.local`` (with ``~`` expanded to the absolute " -"path to your home directory) so you'll need to add ``~/.local/bin`` to your " -"``PATH``. You can set your ``PATH`` permanently by `modifying ~/.profile`_." +"This section covers the basics of how to install Python :term:`packages " +"`." msgstr "" -"Linux や macOS 上では、 ``python -m site --user-base`` を実行した結果の末尾" -"に ``bin`` を追加すれば、ユーザベースのバイナリ置き場となるディレクトリがどこ" -"であるかがわかるでしょう。例えば、このコマンドは大抵の場合に ``~/.local`` " -"(の ``~`` をあなたのホームディレクトリの絶対パスに展開したもの) を表示します" -"が、すると、 ``PATH`` には ``~/.local/bin`` を追加する必要があるということで" -"す。 `~/.profile を修正する `_ ことで ``PATH`` を恒久的" -"に変更することができます。" +"この節では、 Python の :term:`パッケージ ` をインストー" +"ルする方法の基本について示します。" -#: ../source/tutorials/installing-packages.rst:450 +#: ../source/tutorials/installing-packages.rst:10 +#, fuzzy msgid "" -"On Windows you can find the user base binary directory by running ``py -m " -"site --user-site`` and replacing ``site-packages`` with ``Scripts``. For " -"example, this could return ``C:" -"\\Users\\Username\\AppData\\Roaming\\Python36\\site-packages`` so you would " -"need to set your ``PATH`` to include ``C:" -"\\Users\\Username\\AppData\\Roaming\\Python36\\Scripts``. You can set your " -"user ``PATH`` permanently in the `Control Panel`_. You may need to log out " -"for the ``PATH`` changes to take effect." +"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 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." msgstr "" -"Windows 上では、 ``py -m site --user-site`` の結果について ``site-packages`` " -"を ``Scripts`` で置き換えればユーザベースのバイナリ置き場となるディレクトリを" -"見つけることができるでしょう。このコマンドは例えば ``C:" -"\\Users\\Username\\AppData\\Roaming\\Python36\\site-packages`` のような結果を" -"返すので、 ``PATH`` に ``C:" -"\\Users\\Username\\AppData\\Roaming\\Python36\\Scripts`` が含まれるようにする" -"必要があるでしょう。 `Control Panel`_ で恒久的に ``PATH`` を設定することがで" -"きるでしょう。 ``PATH`` の修正が効果を持つには、一旦ログアウトする必要がある" -"かもしれません。" +"この文脈では、 \"パッケージ\" という用語が、インストールされるソフトウェアの" +"束を表すものである (すなわち、 :term:`配布物 ` の同義語" +"である) ことを注記しておくことは重要です。 Python のなんらかのソースコードを" +"インポートする (つまり、モジュール群の) 容れ物としての :term:`パッケージ " +"` のことを指してはいないのです。 Python のコミュニティで" +"は、 :term:`配布物 ` のことを \"パッケージ\" という用語" +"で呼ぶことは一般的に行われています。 Linux ディストロや、 Python そのもののよ" +"うなその他の大きなソフトウェア配布物と紛らわしいので、 \"配布物\" という用語" +"を使うことはしばしば歓迎されません。" -#: ../source/tutorials/installing-packages.rst:466 +#: ../source/tutorials/installing-packages.rst:24 +msgid "Requirements for Installing Packages" +msgstr "パッケージをインストールするための必須事項" + +#: ../source/tutorials/installing-packages.rst:26 msgid "" -"Install a list of requirements specified in a :ref:`Requirements File `." +"This section describes the steps to follow before installing other Python " +"packages." msgstr "" -":ref:`Requirements ファイル ` で指定された一連の必須" -"条件となる依存先をインストールしましょう。" +"この節では、その他の Python パッケージをインストールする前にやっておくべきス" +"テップを記します。" -#: ../source/tutorials/installing-packages.rst:482 -msgid "Installing from VCS" -msgstr "VCS からインストールする" +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +msgstr "コマンドラインから Python を起動できることを確認する" -#: ../source/tutorials/installing-packages.rst:484 +#: ../source/tutorials/installing-packages.rst:33 msgid "" -"Install a project from VCS in \"editable\" mode. For a full breakdown of " -"the syntax, see pip's section on :ref:`VCS Support `." +"Before you go any further, make sure you have Python and that the expected " +"version is available from your command line. You can check this by running:" msgstr "" -"プロジェクトを VCS から \"編集可能\" モードでインストールしましょう。この構文" -"を全て細かく説明したものについては、 :ref:`VCS サポート ` " -"の pip の節を見てください。" +"先へ進む前に、期待通りのバージョンの Python が手元のコマンドラインで動作して" +"いることを確認しておきましょう。つぎのコマンドを実行すれば確認できます:" -#: ../source/tutorials/installing-packages.rst:506 -msgid "Installing from other Indexes" -msgstr "他のインデックスサイトからインストールする" +#: ../source/tutorials/installing-packages.rst:49 +msgid "" +"You should get some output like ``Python 3.6.3``. If you do not have Python, " +"please install the latest 3.x version from `python.org`_ or refer to the :" +"ref:`Installing Python ` section of the " +"Hitchhiker's Guide to Python." +msgstr "" +"``Python 3.6.3`` のような応答が出力されるはずです。もし Python がなければ、最" +"新バージョンの 3.x を `python.org`_ からインストールするか、 Python ユーザの" +"ためのヒッチハイクガイドの :ref:`Python をインストールする ` の節を参照するか、どちらかをしてください。" -#: ../source/tutorials/installing-packages.rst:508 -msgid "Install from an alternate index" -msgstr "代替となるインデックスサイトからインストールする" +#: ../source/tutorials/installing-packages.rst:53 +msgid "If you're a newcomer and you get an error like this:" +msgstr "あなたがまだ慣れていなくて、しかも次のようなエラーに遭遇した場合には:" -#: ../source/tutorials/installing-packages.rst:522 +#: ../source/tutorials/installing-packages.rst:62 msgid "" -"Search an additional index during install, in addition to :term:`PyPI " -"`" +"It's because this command and other suggested commands in this tutorial are " +"intended to be run in a *shell* (also called a *terminal* or *console*). See " +"the Python for Beginners `getting started tutorial`_ for an introduction to " +"using your operating system's shell and interacting with Python." msgstr "" -":term:`PyPI ` に加えて、追加のインデックスサイト" -"をインストール中に探索する" - -#: ../source/tutorials/installing-packages.rst:538 -msgid "Installing from a local src tree" -msgstr "ローカルのソースツリーからインストールする" +"それは、このコマンドや、このチュートリアルに出てくる他のコマンドが、 *シェル" +"* (*ターミナル* とか *コンソール* とも呼ばれます) で動作することを意図してい" +"るからです。オペレーティングシステムのシェルを使って Python とやりとりするた" +"めの導入説明として、初心者のための Python `はじめの第一歩チュートリアル " +"`, i.e. in such a way that the project appears to be " -"installed, but yet is still editable from the src tree." +"If you're using an enhanced shell like IPython or the Jupyter notebook, you " +"can run system commands like those in this tutorial by prefacing them with a " +"``!`` character:" msgstr "" -":doc:`開発モード ` 、すなわち、プロ" -"ジェクトがインストールされていて、しかも、ソースツリーからへんしゅうかのうで" -"あるような方法でローカルのソースツリーからインストールすること。" +"IPython や Jupyter notebook のような拡張されたシェルを使っているのであれば、" +"先頭に ``!`` マークを付けることで、このチュートリアルに出てくるようなシステム" +"コマンドを実行することができます:" -#: ../source/tutorials/installing-packages.rst:558 -msgid "You can also install normally from src" -msgstr "ソースツリーから通常通りにインストールすることも可能" +#: ../source/tutorials/installing-packages.rst:78 +msgid "" +"It's recommended to write ``{sys.executable}`` rather than plain ``python`` " +"in order to ensure that commands are run in the Python installation matching " +"the currently running notebook (which may not be the same Python " +"installation that the ``python`` command refers to)." +msgstr "" +"現在動作している notebook の Python 実装 (これは ``python`` コマンドが実際に" +"呼び出す Python 実装と同じであるとは限らない) で (投入した) コマンドが動作し" +"ていることを確実にするために、 単に ``python`` と書くのではなく ``{sys." +"executable}`` と書くことを推奨します。" -#: ../source/tutorials/installing-packages.rst:573 -msgid "Installing from local archives" -msgstr "ローカルアーカイブからインストールする" +#: ../source/tutorials/installing-packages.rst:83 +msgid "" +"Due to the way most Linux distributions are handling the Python 3 migration, " +"Linux users using the system Python without creating a virtual environment " +"first should replace the ``python`` command in this tutorial with " +"``python3`` and the ``python -m pip`` command with ``python3 -m pip --" +"user``. Do *not* run any of the commands in this tutorial with ``sudo``: if " +"you get a permissions error, come back to the section on creating virtual " +"environments, set one up, and then continue with the tutorial as written." +msgstr "" +"ほとんどの Linux ディストロが Python 3 の移植を扱う方法のせいで、仮想環境を作" +"ること抜きでシステム側の Python を使う Linux ユーザは、まず、このチュートリア" +"ルに出てくる ``python`` コマンドを ``python3`` に、そして、 ``python -m " +"pip`` コマンドを ``python3 -m pip --user`` に置換するべきです。このチュートリ" +"アルに出てくるコマンドを ``sudo`` 付きで実行することは *やめてください*: パー" +"ミッションエラーが発生する場合には、仮想環境の作成の節に戻って仮想環境を作成" +"し、チュートリアルに書かれている通りのやり方で再開してください。" -#: ../source/tutorials/installing-packages.rst:575 -msgid "Install a particular source archive file." -msgstr "特定のソースコードアーカイブファイルをインストールする。" +#: ../source/tutorials/installing-packages.rst:95 +msgid "Ensure you can run pip from the command line" +msgstr "コマンドラインから pip を実行できることを確実にする" -#: ../source/tutorials/installing-packages.rst:589 +#: ../source/tutorials/installing-packages.rst:97 msgid "" -"Install from a local directory containing archives (and don't check :term:" -"`PyPI `)" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" msgstr "" -"アーカイブを含んだローカルのディレクトリから(しかも :term:`PyPI ` をチェックしないで)インストールする" - -#: ../source/tutorials/installing-packages.rst:609 -msgid "Installing from other sources" -msgstr "他の場所からインストールする" +"さらに、 :ref:`pip` コマンドを実行できることを確認しておきましょう。次のコマ" +"ンドで確認できます:" -#: ../source/tutorials/installing-packages.rst:611 +#: ../source/tutorials/installing-packages.rst:112 msgid "" -"To install from other data sources (for example Amazon S3 storage) you can " -"create a helper application that presents the data in a format compliant " -"with the :ref:`simple repository API `:, and use the " -"``--extra-index-url`` flag to direct pip to use that index." +"If you installed Python from source, with an installer from `python.org`_, " +"or via `Homebrew`_ you should already have pip. If you're on Linux and " +"installed using your OS package manager, you may have to install pip " +"separately, see :doc:`/guides/installing-using-linux-tools`." msgstr "" -":ref:`simple repository API ` 準拠のフォーマットに合わ" -"せてデータを表現するようなヘルパーアプリケーションを作成して、 pip を ``--" -"extra-index-url`` フラグでそのインデックスへ向け直すことで、他のデータソース " -"(例えば Amazon S3 ストレージ) からインストールすることができます。" - -#: ../source/tutorials/installing-packages.rst:623 -msgid "Installing Prereleases" -msgstr "リリース前のバージョンをインストールする" +"`python.org`_ から持ってきたインストーラや `Homebrew`_ を使って Python をソー" +"スコードからインストールしたのであれば、すでに pip が動作するはずです。 " +"Linux 上で OS のパッケージ管理機構を使ってインストールしたのであれば、 pip を" +"個別にインストールしなければならないかもしれませんが、この場合は :doc:`/" +"guides/installing-using-linux-tools` を見てください。" -#: ../source/tutorials/installing-packages.rst:625 +#: ../source/tutorials/installing-packages.rst:119 msgid "" -"Find pre-release and development versions, in addition to stable versions. " -"By default, pip only finds stable versions." +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" msgstr "" -"安定バージョンに加えて、リリース前のバージョンや開発中のバージョンを見つけま" -"しょう。デフォルトでは pip は安定バージョンだけを探索します。" +"まだ ``pip`` がインストールされていなければ、初回は標準ライブラリからブートス" +"トラップしてみてください:" -#: ../source/tutorials/installing-packages.rst:641 -msgid "Installing \"Extras\"" -msgstr "パッケージの \"Extras\" をインストールする" +#: ../source/tutorials/installing-packages.rst:134 +msgid "If that still doesn't allow you to run ``python -m pip``:" +msgstr "それでもまだ ``python -m pip`` を実行できないのであれば:" -#: ../source/tutorials/installing-packages.rst:643 +#: ../source/tutorials/installing-packages.rst:136 msgid "" -"Extras are optional \"variants\" of a package, which may include additional " -"dependencies, and thereby enable additional functionality from the package. " -"If you wish to install an extra for a package which you know publishes one, " -"you can include it in the pip installation command:" +"Securely Download `get-pip.py `_ [1]_" msgstr "" -"Extras は、パッケージのオプション的な \"変種\" で、追加的な依存先を加えること" -"も可能であり、従って、パッケージの追加的な機能を有効化することができるもので" -"す。もし、one なる機能を追加するとわかっているパッケージの追加部分 (extra) を" -"インストールしたいのであれば、次のような pip のインストールコマンドを使うこと" -"でそれを追加することができます:" +"`get-pip.py `_ [1]_ をセキュアにダウン" +"ロードする" -#: ../source/tutorials/installing-packages.rst:666 +#: ../source/tutorials/installing-packages.rst:139 msgid "" -"\"Secure\" in this context means using a modern browser or a tool like :" -"command:`curl` that verifies SSL certificates when downloading from https " -"URLs." +"Run ``python get-pip.py``. [2]_ This will install or upgrade pip. " +"Additionally, it will install :ref:`setuptools` and :ref:`wheel` if they're " +"not installed already." msgstr "" -"この文脈での \"Secure\" とは、https の付く URL からダウンロードする際に、近代" -"的なブラウザか :command:`curl` のようなツールを使って SSL 証明書を検証するこ" -"とを意味しています。" +"``python get-pip.py`` を実行してください [2]_ 。これで pip をインストールまた" +"は更新することができます。さらに、まだインストールされていなければ、 :ref:" +"`setuptools` と :ref:`wheel` もインストールされるでしょう。" -#: ../source/tutorials/installing-packages.rst:675 +#: ../source/tutorials/installing-packages.rst:145 msgid "" -"Beginning with Python 3.4, ``venv`` (a stdlib alternative to :ref:" -"`virtualenv`) will create virtualenv environments with ``pip`` pre-" -"installed, thereby making it an equal alternative to :ref:`virtualenv`." +"Be cautious if you're using a Python install that's managed by your " +"operating system or another package manager. get-pip.py does not coordinate " +"with those tools, and may leave your system in an inconsistent state. You " +"can use ``python get-pip.py --prefix=/usr/local/`` to install in ``/usr/" +"local`` which is designed for locally-installed software." msgstr "" -"Python 3.4 以降は (:ref:`virtualenv` の代替物で標準ライブラリに取り込まれた) " -"``venv``があるので、インストール済みの ``pip`` で virtualenv 環境を作成でき、" -"それによって :ref:`virtualenv` の同等な代替物となっています。" +"オペレーティングシステムないし他のパッケージ管理機構を使ってインストールした " +"Python を管理しているなら、用心深くあるべきです。 get-pip.py はそのようなツー" +"ル群と協調して動作する訳ではないので、あなたのシステムの一貫性を破壊するかも" +"しれません。ソフトウェアをローカルにインストールするために設計された ``/usr/" +"local`` にインストールするなら ``python get-pip.py --prefix=/usr/local`` を使" +"うことができます。" -#: ../source/tutorials/installing-packages.rst:680 +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "pip ・ setuptools ・ wheel が最新版であることを確実にする" + +#: ../source/tutorials/installing-packages.rst:156 msgid "" -"The compatible release specifier was accepted in :pep:`440` and support was " -"released in :ref:`setuptools` v8.0 and :ref:`pip` v6.0" +"While ``pip`` alone is sufficient to install from pre-built binary archives, " +"up to date copies of the ``setuptools`` and ``wheel`` projects are useful to " +"ensure you can also install from source archives:" msgstr "" -"互換性のあるリリース指定子は :pep:`440` で受容され、そのサポートが :ref:" -"`setuptools` v8.0 と :ref:``pip` v6.0 でリリースされました" +"``pip`` 単体でも事前にビルドされたバイナリアーカイブからインストールを行うに" +"は十分ですが、最新の ``setuptools`` と ``wheel`` があればソースコードアーカイ" +"ブからでも確実にインストールすることができるので便利です:" -#: ../source/tutorials/managing-dependencies.rst:4 -msgid "Managing Application Dependencies" -msgstr "アプリケーションの依存関係を管理する" +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "必須ではないが、仮想環境を構築する" -#: ../source/tutorials/managing-dependencies.rst:6 +#: ../source/tutorials/installing-packages.rst:175 msgid "" -"The :ref:`package installation tutorial ` covered the " -"basics of getting set up to install and update Python packages." +"See :ref:`section below ` for " +"details, but here's the basic :doc:`venv ` [3]_ command " +"to use on a typical Linux system:" msgstr "" -":ref:`パッケージインストールに関するチュートリアル ` に" -"は、 Python のパッケージをインストールしたり更新したりするための準備の基本が" -"説明されています。" +"詳しいことは、 :ref:`下の節 ` に出て" +"いますので、ここでは基本的な :doc:`venv ` [3]_ コマンド" +"を典型的な Linux システムで使うやり方を説明します:" -#: ../source/tutorials/managing-dependencies.rst:9 +#: ../source/tutorials/installing-packages.rst:192 msgid "" -"However, running these commands interactively can get tedious even for your " -"own personal projects, and things get even more difficult when trying to set " -"up development environments automatically for projects with multiple " -"contributors." +"This will create a new virtual environment in the ``tutorial_env`` " +"subdirectory, and configure the current shell to use it as the default " +"``python`` environment." msgstr "" -"しかしながら、これらのコマンドを対話形式で実行することは、自分自身の個人的な" -"プロジェクト向けであってもうんざりする作業になりかねないし、複数の貢献者が参" -"加するようなプロジェクト向けに開発環境を自動的に設定することを試みる場合には" -"もっと困難にさえなるでしょう。" +"これで新しい仮想環境が ``tutorial_env`` サブディレクトリ内に生成され、それを" +"現在のシェルのデフォルトの ``python`` 環境として使わせることができます。" -#: ../source/tutorials/managing-dependencies.rst:13 -msgid "" -"This tutorial walks you through the use of :ref:`Pipenv` to manage " -"dependencies for an application. It will show you how to install and use the " -"necessary tools and make strong recommendations on best practices." -msgstr "" -"このチュートリアルでは、 :ref:`Pipenv` を使ってアプリケーションの依存関係を管" -"理する方法について一通り見て回ります。必要なツール群のインストールの仕方もお" -"見せしますし、ベストプラクティスについても強い推奨をします。" +#: ../source/tutorials/installing-packages.rst:199 +msgid "Creating Virtual Environments" +msgstr "仮想環境を構築する" -#: ../source/tutorials/managing-dependencies.rst:17 +#: ../source/tutorials/installing-packages.rst:201 msgid "" -"Keep in mind that Python is used for a great many different purposes, and " -"precisely how you want to manage your dependencies may change based on how " -"you decide to publish your software. The guidance presented here is most " -"directly applicable to the development and deployment of network services " -"(including web applications), but is also very well suited to managing " -"development and testing environments for any kind of project." +"Python \"Virtual Environments\" allow Python :term:`packages ` to be installed in an isolated location for a particular " +"application, rather than being installed globally. If you are looking to " +"safely install global command line tools, see :doc:`/guides/installing-stand-" +"alone-command-line-tools`." msgstr "" -"覚えておいてもらいたいのは、 Python が極めて多岐に渡る目的に使用されるという" -"ことと、あなたが自分のソフトウェアを公開するやり方によって依存関係を管理する" -"正確なやり方が変化するであろうということです。ここに書かれているガイダンス" -"は、ネットワークサービス (web アプリケーションを含む) の開発やデプロイメント" -"には最も直接的に適用できますが、どんな種類のプロジェクトであってもその開発や" -"試験のための環境を管理するのにとても適切であると言えるでしょう。" +"Python の \"仮想環境\" を使えば、 Python の :term:`パッケージ ` をグローバルな環境にインストールする代わりに、特定のアプリケーショ" +"ンのための隔離された場所にインストールすることができます。グローバルなコマン" +"ドラインツールを安全にインストールしたいのであれば、 :doc:`/guides/" +"installing-stand-aline-command-line-tools` を見てください。" -#: ../source/tutorials/managing-dependencies.rst:24 +#: ../source/tutorials/installing-packages.rst:207 msgid "" -"For alternatives, see `Other Tools for Application Dependency Management`_." +"Imagine you have an application that needs version 1 of LibFoo, but another " +"application requires version 2. How can you use both these applications? If " +"you install everything into /usr/lib/python3.6/site-packages (or whatever " +"your platform’s standard location is), it’s easy to end up in a situation " +"where you unintentionally upgrade an application that shouldn’t be upgraded." msgstr "" -"他の手段については、 `アプリケーションの依存関係管理のための他のツール群 " -"`_ を見てください。" - -#: ../source/tutorials/managing-dependencies.rst:27 -msgid "Installing Pipenv" -msgstr "Pipenv をインストールする" +"手持ちのあるアプリケーションには LibFoo のバージョン 1 が必要で、しかし、別の" +"アプリケーションではバージョン 2 を要求していると想像してみてください。このよ" +"うなアプリケーションを両方同時に使うためにはどうすれば良いでしょうか？あらゆ" +"るものを /usr/lib/python3.6/site-packages (または、あなたが使っているプラット" +"フォームの標準的な置き場所ならどこでも) にインストールするとすれば、容易く、" +"アップグレードするべきでないはずのアプリケーションを意図せずアップグレードし" +"てしまう結果に終わるでしょう。" -#: ../source/tutorials/managing-dependencies.rst:29 +#: ../source/tutorials/installing-packages.rst:213 msgid "" -":ref:`Pipenv` is a dependency manager for Python projects. If you're " -"familiar with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit " -"to those tools. While :ref:`pip` alone is often sufficient for personal use, " -"Pipenv is recommended for collaborative projects as it's a higher-level tool " -"that simplifies dependency management for common use cases." +"Or more generally, what if you want to install an application and leave it " +"be? If an application works, any change in its libraries or the versions of " +"those libraries can break the application." msgstr "" -":ref:`Pipenv` は Python のプロジェクトの依存関係を管理するツールです。 Node." -"js での `npm`_ や Ruby の `bundler`_ を知っているなら、意図するところはこれら" -"のツールと同じです。個人で使う分には :ref:`pip` さえあれば十分であることが多" -"いですが、共同作業を伴うプロジェクトでは、多くのユースケースにおいて依存関係" -"管理を単純化する上位のツールとして Pipenv が推奨されています。" - -#: ../source/tutorials/managing-dependencies.rst:35 -msgid "Use ``pip`` to install Pipenv:" -msgstr "``pip`` を使って Pipenv をインストールする:" +"あるいは、もっと一般的には、あるアプリケーションをインストールして、そのまま" +"にしておきたいとすればどうでしょう？アプリケーションが動作したとしても、ライ" +"ブラリへの何らかの変更や、ライブラリのバージョン問題でアプリケーションが動作" +"しなくなってしまうかもしれません。" -#: ../source/tutorials/managing-dependencies.rst:51 +#: ../source/tutorials/installing-packages.rst:217 msgid "" -"This does a `user installation`_ to prevent breaking any system-wide " -"packages. If ``pipenv`` isn't available in your shell after installation, " -"you'll need to add the :py:data:`user base `'s binary " -"directory to your ``PATH``. See :ref:`Installing to the User Site` for more " -"information." +"Also, what if you can’t install :term:`packages ` into " +"the global site-packages directory? For instance, on a shared host." msgstr "" -"これは、システムワイドにインストールされたパッケージ群を破壊しないように、 `" -"ユーザインストール `_ を行います。インストール後にシェルか" -"ら ``pipenv`` が利用できない場合は、 :py:data:`ユーザベース ` のバイナリディレクトリを ``PATH`` 変数に追加する必要があるでしょ" -"う。詳しくは、 :ref:`ユーザサイトにインストールする ` を見てください。" +"あるいは、グローバルな site-packages ディレクトリに :term:`パッケージ " +"` をインストールすることができないとしたら、どうでしょ" +"うか？例えば、共有ホストのような。" -#: ../source/tutorials/managing-dependencies.rst:62 -msgid "Installing packages for your project" -msgstr "プロジェクト用にパッケージをインストールする" +#: ../source/tutorials/installing-packages.rst:220 +msgid "" +"In all these cases, virtual environments can help you. They have their own " +"installation directories and they don’t share libraries with other virtual " +"environments." +msgstr "" +"このようなすべての場合において、仮想環境はあなたを助けることができます。仮想" +"環境にはそれぞれのインストール先ディレクトリが別にあって、他の仮想環境とライ" +"ブラリを共有するということがないからです。" -#: ../source/tutorials/managing-dependencies.rst:64 +#: ../source/tutorials/installing-packages.rst:224 msgid "" -"Pipenv manages dependencies on a per-project basis. To install packages, " -"change into your project's directory (or just an empty directory for this " -"tutorial) and run:" +"Currently, there are two common tools for creating Python virtual " +"environments:" msgstr "" -"Pipenv は、プロジェクト毎に依存関係を管理します。パッケージをインストールする" -"には、まずプロジェクト (このチュートリアル用にはからのディレクトリへ行けば十" -"分) のディレクトリへ行って、以下のコマンドを実行してください:" +"現在、ふたつの Python 仮想環境を構築するためのツールがよく知られています:" -#: ../source/tutorials/managing-dependencies.rst:73 +#: ../source/tutorials/installing-packages.rst:226 msgid "" -"Pipenv will install the `Requests`_ library and create a ``Pipfile`` for you " -"in your project's directory. The :ref:`Pipfile` is used to track which " -"dependencies your project needs in case you need to re-install them, such as " -"when you share your project with others. You should get output similar to " -"this (although the exact paths shown will vary):" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` and :ref:`setuptools` into created virtual " +"environments in Python 3.4 and later." msgstr "" -"Pipenv は、 `Requests`_ ライブラリをインストールし、プロジェクトのディレクト" -"リに ``Pipfile`` を作成するでしょう。 :ref:`Pipfile` は、そのプロジェクトを共" -"有している場合などのように、再インストールが必要な時にそのプロジェクトが必要" -"とする依存関係を追跡するために使われます。 (正確なディレクトリパスは変化する" -"としても) これに似た出力が表示されるべきです:" - -#: ../source/tutorials/managing-dependencies.rst:109 -msgid "Using installed packages" -msgstr "インストール済みのパッケージを使う" +":doc:`venv ` は、 Python 3.3 およびそれ以降のバージョン" +"で本体に同梱されていて利用可能であり、 Python 3.4 およびそれ以降では (venv" +"が) :ref:`pip` と :ref:`setuptools` を作成された仮想環境内にインストールしま" +"す。" -#: ../source/tutorials/managing-dependencies.rst:111 +#: ../source/tutorials/installing-packages.rst:229 msgid "" -"Now that Requests is installed you can create a simple :file:`main.py` file " -"to use it:" +":ref:`virtualenv` needs to be installed separately, but supports Python 2.7+ " +"and Python 3.3+, and :ref:`pip`, :ref:`setuptools` and :ref:`wheel` are " +"always installed into created virtual environments by default (regardless of " +"Python version)." msgstr "" -"今や、Requests がインストールされたので、それを使うために単純な :file:`main." -"py` ファイルを作成しましょう:" +":ref:`virtualenv` は別途インストールする必要がありますが、 Python 2.7+ と " +"Python 3.3+ をサポートしており、 :ref:`pip` ・ :ref:`setuptools` ・ :ref:" +"`wheel` を作成された仮想環境に常にデフォルト (Python のバージョンに関係なく) " +"でインストールします。" -#: ../source/tutorials/managing-dependencies.rst:122 -msgid "Then you can run this script using ``pipenv run``:" -msgstr "続いて ``pipenv run`` を使ってこのスクリプトを走らせます:" +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "基本的な使い方は次の通りです:" -#: ../source/tutorials/managing-dependencies.rst:128 -msgid "You should get output similar to this:" -msgstr "大体こんな感じの出力が得られるはずです:" +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr ":doc:`venv ` を使うと:" -#: ../source/tutorials/managing-dependencies.rst:134 +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr ":ref:`virtualenv` を使うと:" + +#: ../source/tutorials/installing-packages.rst:268 msgid "" -"Using ``pipenv run`` ensures that your installed packages are available to " -"your script. It's also possible to spawn a new shell that ensures all " -"commands have access to your installed packages with ``pipenv shell``." +"For more information, see the :doc:`venv ` docs or the :" +"doc:`virtualenv ` docs." msgstr "" -"``pipenv run`` を使うことで、インストール済みのパッケージを確実にスクリプトか" -"ら利用できるようになります。``pipenv shell`` で新しいシェルを立ち上げれば、あ" -"らゆるコマンドからインストール済みパッケージへのアクセスが保証されます。" - -#: ../source/tutorials/managing-dependencies.rst:140 -#: ../source/tutorials/packaging-projects.rst:504 -msgid "Next steps" -msgstr "次なる一歩" +"さらなる説明は、 :doc:`venv ` の説明文書や :doc:" +"`virtualenv ` の説明文書をみてください。" -#: ../source/tutorials/managing-dependencies.rst:142 +#: ../source/tutorials/installing-packages.rst:271 msgid "" -"Congratulations, you now know how to effectively manage dependencies and " -"development environments on a collaborative Python project! ✨ 🍰 ✨" +"The use of :command:`source` under Unix shells ensures that the virtual " +"environment's variables are set within the current shell, and not in a " +"subprocess (which then disappears, having no useful effect)." msgstr "" -"おめでとう、今やあなたは、共同作業を必要とする Python プロジェクトにおいて、" -"依存関係や開発環境を効率良く管理する方法をご存知です！✨ 🍰 ✨" +"UNIX のシェル上で :command:`source` を使うとそのシェル内では仮想環境用の変数" +"が設定されますが、サブシェルでは設定され (ず、役に立つ効果が残り) ません。" -#: ../source/tutorials/managing-dependencies.rst:145 +#: ../source/tutorials/installing-packages.rst:276 +#, fuzzy msgid "" -"If you're interested in creating and distributing your own Python packages, " -"see the :ref:`tutorial on packaging and distributing packages `." +"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:" msgstr "" -"自分で Python パッケージを作成したり配布したりすることに興味があるなら、 :" -"ref:`パッケージングとパッケージ配布のためのチュートリアル ` を見てください。" +"上記のいずれの場合でも、 Windows ユーザは :command:`source` コマンドを使うべ" +"きではあなく、代わりに :command:`activate` スクリプトをコマンドシェルから直接" +"に実行するべきで、例えば次のようにします:" -#: ../source/tutorials/managing-dependencies.rst:148 +#: ../source/tutorials/installing-packages.rst:286 msgid "" -"Note that when your application includes definitions of Python source " -"packages, they (and their dependencies) can be added to your ``pipenv`` " -"environment with ``pipenv install -e `` " -"(e.g. ``pipenv install -e .`` or ``pipenv install -e src``)." +"Managing multiple virtual environments directly can become tedious, so the :" +"ref:`dependency management tutorial ` introduces a " +"higher level tool, :ref:`Pipenv`, that automatically manages a separate " +"virtual environment for each project and application that you work on." msgstr "" -"あなたのアプリケーションが Python ソースコードパッケージの定義を含んでいる場" -"合には、 ``pipenv install -e `` (例えば " -"``pipenv install -e .`` や ``pipenv install -e src``) によって、 (その依存先" -"も含めて) それがあなたの ``pipenv`` 環境にインストールされ得ることに注意して" -"ください。" +"複数の仮想環境をそのままで管理することはうんざりする作業になりがちなので、 :" +"ref:`依存関係を管理するためのチュートリアル ` では、よ" +"り抽象度の高いツール :ref:`Pipenv` を使ってプロジェクトやアプリケーションのそ" +"れぞれのために作成した個別の仮想環境群を自動的に管理する方法を紹介していま" +"す。" -#: ../source/tutorials/managing-dependencies.rst:157 -msgid "Other Tools for Application Dependency Management" -msgstr "アプリケーションの依存関係管理のためのその他のツール" +#: ../source/tutorials/installing-packages.rst:293 +msgid "Use pip for Installing" +msgstr "pip を使ってインストールする" -#: ../source/tutorials/managing-dependencies.rst:159 +#: ../source/tutorials/installing-packages.rst:295 msgid "" -"If you find this particular approach to managing application dependencies " -"isn't working well for you or your use case, you may want to explore these " -"other tools and techniques, listed in alphabetical order, to see if one of " -"them is a better fit:" +":ref:`pip` is the recommended installer. Below, we'll cover the most common " +"usage scenarios. For more detail, see the :doc:`pip docs `, which " +"includes a complete :doc:`Reference Guide `." msgstr "" -"アプリケーションの依存関係管理で、あなたのユースケースではこの特定のアプロー" -"チがあまりうまく働かないことがわかったならば、この後にアルファベット順に列挙" -"する他のツール群やテクニックがより上手く使えるかどうか試してみたくなるかもし" -"れません:" +":ref:`pip` は推奨されているインストーラです。以下に最もよくある使用シナリオを" +"挙げます。より詳しくは、 :doc:`リファレンスガイド ` の全体を含" +"む :doc:`pip 説明文書 ` を見てください。" -#: ../source/tutorials/managing-dependencies.rst:163 -msgid "" -"`hatch `_ for opinionated coverage of even " -"more steps in the project management workflow, such as incrementing versions " -"and creating new skeleton projects from project templates." -msgstr "" -"`hatch `_ は、プロジェクト管理のワークフローに" -"おいて、バージョン番号の増やし方やテンプレートから新しいスケルトンプロジェク" -"トを作成するやり方など、ステップ数は増えてもこだわりのあるやり方でやろうとす" -"るツールです。" +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "PyPI からインストールする" -#: ../source/tutorials/managing-dependencies.rst:166 +#: ../source/tutorials/installing-packages.rst:303 +#, fuzzy msgid "" -"`micropipenv `_ for a " -"lightweight wrapper around pip that supports ``requirements.txt``, Pipenv " -"and Poetry lock files, or converting them to pip-tools compatible output. " -"Designed for containerized Python applications, but not limited to them." +"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 `. A full description of the " +"supported specifiers can be found in the :ref:`Version specifier " +"specification `. Below are some examples." msgstr "" -"`micropipenv `_ は、 pip に対す" -"る軽量のラッパで ``requirements.txt`` や Pipenv や Poetry のロックファイル、" -"あるいはそれらを pip ツールと互換性のある形への変換出力をサポートするツールで" -"す。コンテナ化された Python アプリケーションのために設計されましたが、用途は" -"それに限りません。" +":ref:`pip` の最もよくある使い方は、 :term:`要求事項指定子 ` を用いて :term:`Python パッケージインデックス ` からインストールすることです。一般的には、要求事項識別子は、プ" +"ロジェクト名と後続する省略可能な :term:`バージョン指定子 ` で構成されています。 :pep:`440` に、現在サポートされている識別子" +"の :pep:`完全な仕様 <440#version-specifiers>` があります。以下にいくつかの例" +"を挙げます。" -#: ../source/tutorials/managing-dependencies.rst:170 -msgid "" -"`PDM `_ for a modern Python package " -"management relying on standards such as :pep:`517` and :pep:`621`." +#: ../source/tutorials/installing-packages.rst:311 +msgid "To install the latest version of \"SomeProject\":" +msgstr "\"とあるプロジェクト\" の最新版をインストールするには:" + +#: ../source/tutorials/installing-packages.rst:325 +msgid "To install a specific version:" +msgstr "特定のバージョンをインストールするには:" + +#: ../source/tutorials/installing-packages.rst:339 +msgid "To install greater than or equal to one version and less than another:" msgstr "" -"`PDM `_ は、 :pep:`517` や :pep:`621` の" -"ような標準に立脚した近代的な Python パッケージ管理ツールです。" +"あるバージョンと同じか新しいバージョンで、もう一つのものより古いものをインス" +"トールするには:" -#: ../source/tutorials/managing-dependencies.rst:172 +#: ../source/tutorials/installing-packages.rst:354 +#, fuzzy msgid "" -"`pip-tools `_ for creating a lock " -"file of all dependencies from a list of packages directly used in a project, " -"and ensuring that only those dependencies are installed." +"To install a version that's :ref:`compatible ` with a certain version: [4]_" msgstr "" -"`pip-tools `_ は、プロジェクト内で直接" -"使われているパッケージのリストから全ての依存関係のロックファイルを生成する" -"ツールで、依存関係に現れるものだけがインストールされていることを保証します。" +"あるバージョンと :pep:`\"互換性がある\" <440#compatible-release>` バージョン" +"をインストールするには: [4]_" -#: ../source/tutorials/managing-dependencies.rst:175 +#: ../source/tutorials/installing-packages.rst:369 msgid "" -"`Poetry `__ for a tool comparable " -"in scope to Pipenv that focuses more directly on use cases where the project " -"being managed is structured as a distributable Python package with a valid " -"``pyproject.toml`` file. By contrast, Pipenv explicitly avoids making the " -"assumption that the application being worked on will support distribution as " -"a ``pip``-installable Python package." +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." msgstr "" -"`Poetry `__ は、そのカバーする範囲と" -"いう点で Pipenv と互換性のあるツールで、 ``pyproject.toml`` ファイルを使った" -"配布可能な Python パッケージとしてプロジェクト管理のユースケースが構成されて" -"いる場合にもっと直接に使用することに焦点を当てたものです。これとは対照的に、 " -"Pipenv は明示的に、 (開発) 作業中のアプリケーションが ``pip`` でインストール" -"可能な Python パッケージとしての配布をサポートしているという仮定を置くことを" -"避けています。" +"この場合には、 \"==1.4.*\" で、かつ、 \">=1.4.2\" であるバージョンをインス" +"トールするという意味になります。" -#: ../source/tutorials/packaging-projects.rst:2 -msgid "Packaging Python Projects" -msgstr "Python のプロジェクトをパッケージングする" +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "ソースコード配布物 vs. Wheels" + +#: ../source/tutorials/installing-packages.rst:376 +msgid "" +":ref:`pip` can install from either :term:`Source Distributions (sdist) " +"` or :term:`Wheels `, but if both " +"are present on PyPI, pip will prefer a compatible :term:`wheel `. You " +"can override pip`s default behavior by e.g. using its :ref:`--no-binary ` option." +msgstr "" +":ref:`pip` は、 :term:`ソースコード配布物 (sdist) ` または :term:`Wheels ` のどちらからでもインストールするこ" +"とができますが、両方が PyPI に存在している場合には pip は互換性のある :term:" +"`wheel ` を選好します。例えば :ref:`--no-binary ` オプションを使うことで pip のデフォルト動作を上書き修正することがで" +"きます。" -#: ../source/tutorials/packaging-projects.rst:4 +#: ../source/tutorials/installing-packages.rst:382 msgid "" -"This tutorial walks you through how to package a simple Python project. It " -"will show you how to add the necessary files and structure to create the " -"package, how to build the package, and how to upload it to the Python " -"Package Index (PyPI)." +":term:`Wheels ` are a pre-built :term:`distribution ` format that provides faster installation compared to :term:`Source " +"Distributions (sdist) `, especially when " +"a project contains compiled extensions." msgstr "" -"このチュートリアルでは、簡単な Python プロジェクトをどのようにしてパッケージ" -"するのかについて、一通り見て回ります。パッケージを構成するために必要なファイ" -"ルやディレクトリを追加する方法や、パッケージをビルドする方法、そして、Python " -"パッケージインデックス (PyPI) にパッケージをアップロードする方法をお見せしま" -"す。" +":term:`Wheels ` は、ビルド済みの :term:`配布物 ` フォーマットで、特にプロジェクトがコンパイル済み拡張を含んでいる場" +"合には、 :term:`ソースコード配布物 (sdist) ` に比べてより短時間でインストールすることができます。" -#: ../source/tutorials/packaging-projects.rst:10 +#: ../source/tutorials/installing-packages.rst:387 msgid "" -"If you have trouble running the commands in this tutorial, please copy the " -"command and its output, then `open an issue`_ on the `packaging-problems`_ " -"repository on GitHub. We'll do our best to help you!" +"If :ref:`pip` does not find a wheel to install, it will locally build a " +"wheel and cache it for future installs, instead of rebuilding the source " +"distribution in the future." msgstr "" -"このチュートリアルに出てくるコマンドを実行したら問題が発生したという場合に" -"は、コマンドと結果出力をコピーして、 GitHub の `packaging-problems`_ リポジト" -"リで `新たな課題 `_ を追加してください。我々が全力であなたをお" -"助けします！" +":ref:`pip` がインストールするべき wheel を発見できなかった場合には、手元で " +"wheel をビルドして、将来のインストール時に再びソースコード配布物からリビルド" +"しないで済むようにキャッシュしておきます。" -#: ../source/tutorials/packaging-projects.rst:18 -msgid "" -"Some of the commands require a newer version of :ref:`pip`, so start by " -"making sure you have the latest version installed:" +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." msgstr "" -"コマンドの中のいくつかは新しめのバージョンの :ref:`pip` でないとだめなので、" -"最新版をインストールして使っていることを最初に確認しておいてください:" +"インストール済みの ``とあるプロジェクト`` を PyPI から最新版に更新する。" -#: ../source/tutorials/packaging-projects.rst:35 -msgid "A simple project" -msgstr "単純なプロジェクト" +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "ユーザサイトへインストールする" -#: ../source/tutorials/packaging-projects.rst:37 +#: ../source/tutorials/installing-packages.rst:414 msgid "" -"This tutorial uses a simple project named " -"``example_package_YOUR_USERNAME_HERE``. If your username is ``me``, then the " -"package would be ``example_package_me``; this ensures that you have a unique " -"package name that doesn't conflict with packages uploaded by other people " -"following this tutorial. We recommend following this tutorial as-is using " -"this project, before packaging your own project." +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" msgstr "" -"このチュートリアルは、 ``example_package_YOUR_USERNAME_HERE`` という名前の単" -"純なプロジェクトを使っています。もしあなたのユーザ名が ``me`` であるなら、" -"パッケージの名前は ``example_package_me`` となるでしょう; こうすることで、こ" -"のチュートリアルに従っている他の人たちがアップロードするパッケージ群と名前が" -"衝突することのない一意なパッケージ名を使っていることを保証できます。自分自身" -"のプロジェクトのパッケージングを始める前に、このプロジェクト名を使ってこの" -"チュートリアルに沿った練習をすることをお勧めします。" +":term:`パッケージ ` を現在のユーザだけが使えるように他" +"から隔離してインストールするには ``--user`` フラグを使います:" -#: ../source/tutorials/packaging-projects.rst:44 -msgid "Create the following file structure locally:" -msgstr "ローカルに以下のファイル構造を作成する:" +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" +"もっと詳しい情報を知りたければ、pip 説明文書の `ユーザ限定のインストール " +"`_ の節を見てくださ" +"い。" -#: ../source/tutorials/packaging-projects.rst:54 +#: ../source/tutorials/installing-packages.rst:433 msgid "" -"The directory containing the Python files should match the project name. " -"This simplifies the configuration and is more obvious to users who install " -"the package." +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." msgstr "" -"Python ファイル群を格納するディレクトリは、プロジェクト名と同じ名前であるべき" -"です。こうすることで設定が簡単になり、また、パッケージをインストールするユー" -"ザから見てより明白になります。" +"仮想環境の中では ``--user`` フラグが無効になることに注意してください - すべて" +"のインストールコマンドが仮想環境に影響を与えます。" -#: ../source/tutorials/packaging-projects.rst:57 -#, fuzzy +#: ../source/tutorials/installing-packages.rst:436 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 " -"[#namespace-packages]_." +"If ``SomeProject`` defines any command-line scripts or console entry points, " +"``--user`` will cause them to be installed inside the `user base`_'s binary " +"directory, which may or may not already be present in your shell's :envvar:" +"`PATH`. (Starting in version 10, pip displays a warning when installing any " +"scripts to a directory outside :envvar:`PATH`.) If the scripts are not " +"available in your shell after installation, you'll need to add the directory " +"to your :envvar:`PATH`:" msgstr "" -"パッケージとしてのディレクトリをインポートするには :file:`__init__.py` が存在" -"していなければならず、また、それは空であるべきです。" +"``とあるプロジェクト`` がコマンドラインスクリプトかコンソールエントリポイント" +"をひとつでも定義しているのであれば、 ``--user`` を与えることで 、 `ユーザベー" +"ス `_ のバイナリ置き場、それがシェルの :envvar:`PATH` 変数にあろう" +"がなかろうが、そこにインストールすることになるでしょう (バージョン 10 以降の " +"pip では、スクリプトを :envvar:`PATH` に含まれていないパスにインストールする" +"時には警告を表示します)。インストール後にスクリプトが利用可能でない場合に" +"は、 :envvar:`PATH` にそのディレクトリパスを追加する必要があるでしょう:" -#: ../source/tutorials/packaging-projects.rst:60 +#: ../source/tutorials/installing-packages.rst:444 msgid "" -":file:`example.py` is an example of a module within the package that could " -"contain the logic (functions, classes, constants, etc.) of your package. " -"Open that file and enter the following content:" +"On Linux and macOS you can find the user base binary directory by running " +"``python -m site --user-base`` and adding ``bin`` to the end. For example, " +"this will typically print ``~/.local`` (with ``~`` expanded to the absolute " +"path to your home directory) so you'll need to add ``~/.local/bin`` to your " +"``PATH``. You can set your ``PATH`` permanently by `modifying ~/.profile`_." msgstr "" -":file:`example.py` は、パッケージの中であなたのパッケージのロジック (関数・ク" -"ラス・定数・その他) を含むであろうモジュールの例です。このファイルを開いて、" -"以下の内容を入力してください:" +"Linux や macOS 上では、 ``python -m site --user-base`` を実行した結果の末尾" +"に ``bin`` を追加すれば、ユーザベースのバイナリ置き場となるディレクトリがどこ" +"であるかがわかるでしょう。例えば、このコマンドは大抵の場合に ``~/.local`` " +"(の ``~`` をあなたのホームディレクトリの絶対パスに展開したもの) を表示します" +"が、すると、 ``PATH`` には ``~/.local/bin`` を追加する必要があるということで" +"す。 `~/.profile を修正する `_ ことで ``PATH`` を恒久的" +"に変更することができます。" -#: ../source/tutorials/packaging-projects.rst:69 +#: ../source/tutorials/installing-packages.rst:450 msgid "" -"If you are unfamiliar with Python's :term:`modules ` and :term:" -"`import packages `, take a few minutes to read over the " -"`Python documentation for packages and modules`_." +"On Windows you can find the user base binary directory by running ``py -m " +"site --user-site`` and replacing ``site-packages`` with ``Scripts``. For " +"example, this could return ``C:" +"\\Users\\Username\\AppData\\Roaming\\Python36\\site-packages`` so you would " +"need to set your ``PATH`` to include ``C:" +"\\Users\\Username\\AppData\\Roaming\\Python36\\Scripts``. You can set your " +"user ``PATH`` permanently in the `Control Panel`_. You may need to log out " +"for the ``PATH`` changes to take effect." msgstr "" -"Python における :term:`モジュール ` や :term:`パッケージのインポート " -"` に馴染みがなければ、数分を費やして `パッケージとモジュール" -"に関する Python の説明文書 `_ " -"を読み通してください。" +"Windows 上では、 ``py -m site --user-site`` の結果について ``site-packages`` " +"を ``Scripts`` で置き換えればユーザベースのバイナリ置き場となるディレクトリを" +"見つけることができるでしょう。このコマンドは例えば ``C:" +"\\Users\\Username\\AppData\\Roaming\\Python36\\site-packages`` のような結果を" +"返すので、 ``PATH`` に ``C:" +"\\Users\\Username\\AppData\\Roaming\\Python36\\Scripts`` が含まれるようにする" +"必要があるでしょう。 `Control Panel`_ で恒久的に ``PATH`` を設定することがで" +"きるでしょう。 ``PATH`` の修正が効果を持つには、一旦ログアウトする必要がある" +"かもしれません。" -#: ../source/tutorials/packaging-projects.rst:73 +#: ../source/tutorials/installing-packages.rst:466 msgid "" -"Once you create this structure, you'll want to run all of the commands in " -"this tutorial within the ``packaging_tutorial`` directory." +"Install a list of requirements specified in a :ref:`Requirements File `." msgstr "" -"この構造さえ作れば、このチュートリアルに出てくるすべてのコマンドを " -"``packaging_tutorial`` ディレクトリで実行したくなるでしょう。" +":ref:`Requirements ファイル ` で指定された一連の必須" +"条件となる依存先をインストールしましょう。" -#: ../source/tutorials/packaging-projects.rst:81 -msgid "Creating the package files" -msgstr "パッケージファイルを作成する" +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "VCS からインストールする" -#: ../source/tutorials/packaging-projects.rst:83 +#: ../source/tutorials/installing-packages.rst:484 msgid "" -"You will now add files that are used to prepare the project for " -"distribution. When you're done, the project structure will look like this:" +"Install a project from VCS in \"editable\" mode. For a full breakdown of " +"the syntax, see pip's section on :ref:`VCS Support `." msgstr "" -"ここで、プロジェクトの配布を準備するために使われるファイル群を追加しましょ" -"う。それが終わったら、プロジェクトの構造はこんな風になっていることでしょう:" +"プロジェクトを VCS から \"編集可能\" モードでインストールしましょう。この構文" +"を全て細かく説明したものについては、 :ref:`VCS サポート ` " +"の pip の節を見てください。" -#: ../source/tutorials/packaging-projects.rst:101 -msgid "Creating a test directory" -msgstr "test ディレクトリを作成する" +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "他のインデックスサイトからインストールする" -#: ../source/tutorials/packaging-projects.rst:103 -msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." -msgstr "" -":file:`tests/` は、テスト用のファイルを置くためのプレースホルダーです。現段階" -"では、空のままにしておいてください。" +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "代替となるインデックスサイトからインストールする" -#: ../source/tutorials/packaging-projects.rst:109 -msgid "Choosing a build backend" +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" msgstr "" +":term:`PyPI ` に加えて、追加のインデックスサイト" +"をインストール中に探索する" -#: ../source/tutorials/packaging-projects.rst:111 +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "ローカルのソースツリーからインストールする" + +#: ../source/tutorials/installing-packages.rst:541 msgid "" -"Tools like :ref:`pip` and :ref:`build` do not actually convert your sources " -"into a :term:`distribution package ` (like a wheel); " -"that job is performed by a :term:`build backend `. The build " -"backend determines how your project will specify its configuration, " -"including metadata (information about the project, for example, the name and " -"tags that are displayed on PyPI) and input files. Build backends have " -"different levels of functionality, such as whether they support building :" -"term:`extension modules `, and you should choose one that " -"suits your needs and preferences." +"Installing from local src in :doc:`Development Mode `, i.e. in such a way that the project appears to be " +"installed, but yet is still editable from the src tree." msgstr "" +":doc:`開発モード ` 、すなわち、プロ" +"ジェクトがインストールされていて、しかも、ソースツリーからへんしゅうかのうで" +"あるような方法でローカルのソースツリーからインストールすること。" -#: ../source/tutorials/packaging-projects.rst:120 -#, fuzzy +#: ../source/tutorials/installing-packages.rst:558 +msgid "You can also install normally from src" +msgstr "ソースツリーから通常通りにインストールすることも可能" + +#: ../source/tutorials/installing-packages.rst:573 +msgid "Installing from local archives" +msgstr "ローカルアーカイブからインストールする" + +#: ../source/tutorials/installing-packages.rst:575 +msgid "Install a particular source archive file." +msgstr "特定のソースコードアーカイブファイルをインストールする。" + +#: ../source/tutorials/installing-packages.rst:589 msgid "" -"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 `." +"Install from a local directory containing archives (and don't check :term:" +"`PyPI `)" msgstr "" -":file:`pyproject.toml` は、 :ref:`pip` や :ref:`build` のような \"フロントエ" -"ンド\" のビルドツールに対して、どの \"backend\"を使ってそのプロジェクトの :" -"term:`配布パッケージ ` を作成するべきかを指定します。" -"バックエンドの選択肢は多数あります; このチュートリアルでは :ref:`Hatchling " -"` をデフォルトとして使っていますが、 :ref:`メタデータの設定 " -"` のための ``[project]`` テーブルをサポートしてさえいれ" -"ば :ref:`setuptools` ・ :ref:`Flit ` ・ :ref:`PDM ` やその他のツー" -"ルでも同じように動作することでしょう。" +"アーカイブを含んだローカルのディレクトリから(しかも :term:`PyPI ` をチェックしないで)インストールする" -#: ../source/tutorials/packaging-projects.rst:127 +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "他の場所からインストールする" + +#: ../source/tutorials/installing-packages.rst:611 msgid "" -"Some build backends are part of larger tools that provide a command-line " -"interface with additional features like project initialization and version " -"management, as well as building, uploading, and installing packages. This " -"tutorial uses single-purpose tools that work independently." +"To install from other data sources (for example Amazon S3 storage) you can " +"create a helper application that presents the data in a format compliant " +"with the :ref:`simple repository API `:, and use the " +"``--extra-index-url`` flag to direct pip to use that index." msgstr "" -"ビルド・アップロード・インストールと並んでプロジェクト初期化やバージョン管理" -"のような追加機能を伴ったコマンドラインインタフェースを提供する、もっと大きな" -"ツールの一部を構成するビルドバックエンドもあります。このチュートリアルでは、" -"独立に動作する単一目的のツールを扱います。" +":ref:`simple repository API ` 準拠のフォーマットに合わ" +"せてデータを表現するようなヘルパーアプリケーションを作成して、 pip を ``--" +"extra-index-url`` フラグでそのインデックスへ向け直すことで、他のデータソース " +"(例えば Amazon S3 ストレージ) からインストールすることができます。" -#: ../source/tutorials/packaging-projects.rst:132 +#: ../source/tutorials/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "リリース前のバージョンをインストールする" + +#: ../source/tutorials/installing-packages.rst:625 msgid "" -"The :file:`pyproject.toml` tells :term:`build frontend ` " -"tools like :ref:`pip` and :ref:`build` which backend to use for your " -"project. Below are some examples for common build backends, but check your " -"backend's own documentation for more details." +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." msgstr "" +"安定バージョンに加えて、リリース前のバージョンや開発中のバージョンを見つけま" +"しょう。デフォルトでは pip は安定バージョンだけを探索します。" -#: ../source/tutorials/packaging-projects.rst:170 +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "パッケージの \"Extras\" をインストールする" + +#: ../source/tutorials/installing-packages.rst:643 msgid "" -"The ``requires`` key is a list of packages that are needed to build your " -"package. The :term:`frontend ` should install them " -"automatically when building your package. Frontends usually run builds in " -"isolated environments, so omitting dependencies here may cause build-time " -"errors. This should always include your backend's package, and might have " -"other build-time dependencies." +"Extras are optional \"variants\" of a package, which may include additional " +"dependencies, and thereby enable additional functionality from the package. " +"If you wish to install an extra for a package which you know publishes one, " +"you can include it in the pip installation command:" msgstr "" +"Extras は、パッケージのオプション的な \"変種\" で、追加的な依存先を加えること" +"も可能であり、従って、パッケージの追加的な機能を有効化することができるもので" +"す。もし、one なる機能を追加するとわかっているパッケージの追加部分 (extra) を" +"インストールしたいのであれば、次のような pip のインストールコマンドを使うこと" +"でそれを追加することができます:" -#: ../source/tutorials/packaging-projects.rst:177 -#, fuzzy +#: ../source/tutorials/installing-packages.rst:666 msgid "" -"The ``build-backend`` key is the name of the Python object that frontends " -"will use to perform the build." +"\"Secure\" in this context means using a modern browser or a tool like :" +"command:`curl` that verifies SSL certificates when downloading from https " +"URLs." msgstr "" -"``build-backend`` は、そのフロントエンドがビルドを実行するにあたって使用する" -"であろう Python オブジェクトの名前です。" +"この文脈での \"Secure\" とは、https の付く URL からダウンロードする際に、近代" +"的なブラウザか :command:`curl` のようなツールを使って SSL 証明書を検証するこ" +"とを意味しています。" -#: ../source/tutorials/packaging-projects.rst:180 +#: ../source/tutorials/installing-packages.rst:675 msgid "" -"Both of these values will be provided by the documentation for your build " -"backend, or generated by its command line interface. There should be no need " -"for you to customize these settings." +"Beginning with Python 3.4, ``venv`` (a stdlib alternative to :ref:" +"`virtualenv`) will create virtualenv environments with ``pip`` pre-" +"installed, thereby making it an equal alternative to :ref:`virtualenv`." msgstr "" +"Python 3.4 以降は (:ref:`virtualenv` の代替物で標準ライブラリに取り込まれた) " +"``venv``があるので、インストール済みの ``pip`` で virtualenv 環境を作成でき、" +"それによって :ref:`virtualenv` の同等な代替物となっています。" -#: ../source/tutorials/packaging-projects.rst:184 +#: ../source/tutorials/installing-packages.rst:680 msgid "" -"Additional configuration of the build tool will either be in a ``tool`` " -"section of the ``pyproject.toml``, or in a special file defined by the build " -"tool. For example, when using ``setuptools`` as your build backend, " -"additional configuration may be added to a ``setup.py`` or ``setup.cfg`` " -"file, and specifying ``setuptools.build_meta`` in your build allows the " -"tools to locate and use these automatically." +"The compatible release specifier was accepted in :pep:`440` and support was " +"released in :ref:`setuptools` v8.0 and :ref:`pip` v6.0" msgstr "" +"互換性のあるリリース指定子は :pep:`440` で受容され、そのサポートが :ref:" +"`setuptools` v8.0 と :ref:``pip` v6.0 でリリースされました" -#: ../source/tutorials/packaging-projects.rst:194 -msgid "Configuring metadata" -msgstr "メタデータを設定する" +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "アプリケーションの依存関係を管理する" -#: ../source/tutorials/packaging-projects.rst:196 +#: ../source/tutorials/managing-dependencies.rst:6 msgid "" -"Open :file:`pyproject.toml` and enter the following content. Change the " -"``name`` to include your username; this ensures that you have a unique " -"package name that doesn't conflict with packages uploaded by other people " -"following this tutorial." +"The :ref:`package installation tutorial ` covered the " +"basics of getting set up to install and update Python packages." msgstr "" -":file:`pyproject.toml` を開いて、以下の内容を入力してください。 ``name`` の値" -"はあなたのユーザ名に書き換えてください; こうすることで、このチュートリアルを" -"履修している他の人たちがアップロードするパッケージと衝突を起こさない一意な" -"パッケージ名を使っていることを保証することができます。" +":ref:`パッケージインストールに関するチュートリアル ` に" +"は、 Python のパッケージをインストールしたり更新したりするための準備の基本が" +"説明されています。" -#: ../source/tutorials/packaging-projects.rst:222 +#: ../source/tutorials/managing-dependencies.rst:9 msgid "" -"``name`` is the *distribution name* of your package. This can be any name as " -"long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also " -"must not already be taken on PyPI. **Be sure to update this with your " -"username** for this tutorial, as this ensures you won't try to upload a " -"package with the same name as one which already exists." +"However, running these commands interactively can get tedious even for your " +"own personal projects, and things get even more difficult when trying to set " +"up development environments automatically for projects with multiple " +"contributors." msgstr "" -"``name`` は、あなたのパッケージの *配布物の名前* です。これは、文字・数字・ " -"``.`` ・ ``_`` ・ ``-`` だけで構成されている限りは、どんな名前でも構いませ" -"ん。また、 PyPI 上に既に存在するものであってはなりません。このチュートリアル" -"では、あなたのユーザ名を使って更新していることを **確実にしてください** 、と" -"いうのは、そうすることで、既存の名前と同じ名前のパッケージのアップロードを試" -"みることがないと保証できるからです。" +"しかしながら、これらのコマンドを対話形式で実行することは、自分自身の個人的な" +"プロジェクト向けであってもうんざりする作業になりかねないし、複数の貢献者が参" +"加するようなプロジェクト向けに開発環境を自動的に設定することを試みる場合には" +"もっと困難にさえなるでしょう。" -#: ../source/tutorials/packaging-projects.rst:227 -#, fuzzy +#: ../source/tutorials/managing-dependencies.rst:13 msgid "" -"``version`` is the package version. (Some build backends allow it to be " -"specified another way, such as from a file or Git tag.)" +"This tutorial walks you through the use of :ref:`Pipenv` to manage " +"dependencies for an application. It will show you how to install and use the " +"necessary tools and make strong recommendations on best practices." msgstr "" -"``version`` は、パッケージのバージョン番号です。バージョン番号についてもっと" -"詳細に知りたい場合は、 :ref:`バージョン指定子 ` を見てく" -"ださい。ビルドバックエンドの中には、ファイルから、もしくは、 git のタグからの" -"ように、別の方法で指定することを許容するものもあります。" +"このチュートリアルでは、 :ref:`Pipenv` を使ってアプリケーションの依存関係を管" +"理する方法について一通り見て回ります。必要なツール群のインストールの仕方もお" +"見せしますし、ベストプラクティスについても強い推奨をします。" -#: ../source/tutorials/packaging-projects.rst:229 +#: ../source/tutorials/managing-dependencies.rst:17 msgid "" -"``authors`` is used to identify the author of the package; you specify a " -"name and an email for each author. You can also list ``maintainers`` in the " -"same format." +"Keep in mind that Python is used for a great many different purposes, and " +"precisely how you want to manage your dependencies may change based on how " +"you decide to publish your software. The guidance presented here is most " +"directly applicable to the development and deployment of network services " +"(including web applications), but is also very well suited to managing " +"development and testing environments for any kind of project." msgstr "" -"``authors`` は、パッケージの作者を識別するために使われます; 作者の一人一人に" -"ついて名前と電子メールアドレスを指定します。同じフォーマットで " -"``maintainers`` を列挙することもできます。" - -#: ../source/tutorials/packaging-projects.rst:232 -msgid "``description`` is a short, one-sentence summary of the package." -msgstr "``description`` は、１文で短くパッケージを説明するものです。" +"覚えておいてもらいたいのは、 Python が極めて多岐に渡る目的に使用されるという" +"ことと、あなたが自分のソフトウェアを公開するやり方によって依存関係を管理する" +"正確なやり方が変化するであろうということです。ここに書かれているガイダンス" +"は、ネットワークサービス (web アプリケーションを含む) の開発やデプロイメント" +"には最も直接的に適用できますが、どんな種類のプロジェクトであってもその開発や" +"試験のための環境を管理するのにとても適切であると言えるでしょう。" -#: ../source/tutorials/packaging-projects.rst:233 -#, fuzzy +#: ../source/tutorials/managing-dependencies.rst:24 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:`pyproject." -"toml guide `." +"For alternatives, see `Other Tools for Application Dependency Management`_." msgstr "" -"``readme`` は、パッケージに関する詳細な説明を含んだファイルへのパスです。 " -"PyPI 上のパッケージ詳細のページにこの内容が表示されます。この場合、説明の文言" -"は :file:`README.md` (これがよくあるパターンです) からロードされます。他に" -"も、 :ref:`プロジェクトのメタデータの仕様 ` に記" -"述されているもっと先進的なテーブル形式があります。" +"他の手段については、 `アプリケーションの依存関係管理のための他のツール群 " +"`_ を見てください。" -#: ../source/tutorials/packaging-projects.rst:238 -#, fuzzy +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "Pipenv をインストールする" + +#: ../source/tutorials/managing-dependencies.rst:29 msgid "" -"``requires-python`` gives the versions of Python supported by your project. " -"An installer like :ref:`pip` will look back through older versions of " -"packages until it finds one that has a matching Python version." +":ref:`Pipenv` is a dependency manager for Python projects. If you're " +"familiar with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit " +"to those tools. While :ref:`pip` alone is often sufficient for personal use, " +"Pipenv is recommended for collaborative projects as it's a higher-level tool " +"that simplifies dependency management for common use cases." msgstr "" -"``requires-python`` は、そのプロジェクトがサポートしている Python のバージョ" -"ンを与えます。 :ref:`pip` のようなインストーラは、 Python バージョンが合致す" -"るものまでパッケージのバージョンを遡って探索します。" +":ref:`Pipenv` は Python のプロジェクトの依存関係を管理するツールです。 Node." +"js での `npm`_ や Ruby の `bundler`_ を知っているなら、意図するところはこれら" +"のツールと同じです。個人で使う分には :ref:`pip` さえあれば十分であることが多" +"いですが、共同作業を伴うプロジェクトでは、多くのユースケースにおいて依存関係" +"管理を単純化する上位のツールとして Pipenv が推奨されています。" -#: ../source/tutorials/packaging-projects.rst:241 +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "``pip`` を使って Pipenv をインストールする:" + +#: ../source/tutorials/managing-dependencies.rst:51 msgid "" -"``classifiers`` gives the index and :ref:`pip` some additional metadata " -"about your package. In this case, the package is only compatible with Python " -"3, is licensed under the MIT license, and is OS-independent. You should " -"always include at least which version(s) of Python your package works on, " -"which license your package is available under, and which operating systems " -"your package will work on. For a complete list of classifiers, see https://" -"pypi.org/classifiers/." +"This does a `user installation`_ to prevent breaking any system-wide " +"packages. If ``pipenv`` isn't available in your shell after installation, " +"you'll need to add the :py:data:`user base `'s binary " +"directory to your ``PATH``. See :ref:`Installing to the User Site` for more " +"information." msgstr "" -"``classifiers`` は、インデックスと :ref:`pip` に、そのパッケージに関する追加" -"的なメタデータをいくつか与えます。この場合には、当該パッケージは Python 3 で" -"のみ動作し、 MIT ライセンスの下に従うものであり、 OS には依らず独立のもので" -"す。どのバージョンの Python 上でそのパッケージが動作するのか、どのライセンス" -"に従うのか、どのオペレーティングシステムで動作するのかを示しておくことは、常" -"に最低限それだけはやるべきことです。 classifiers の完全なリストについては、 " -"https://pypi.org/classifiers/ を見てください。" +"これは、システムワイドにインストールされたパッケージ群を破壊しないように、 `" +"ユーザインストール `_ を行います。インストール後にシェルか" +"ら ``pipenv`` が利用できない場合は、 :py:data:`ユーザベース ` のバイナリディレクトリを ``PATH`` 変数に追加する必要があるでしょ" +"う。詳しくは、 :ref:`ユーザサイトにインストールする ` を見てください。" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "プロジェクト用にパッケージをインストールする" -#: ../source/tutorials/packaging-projects.rst:248 +#: ../source/tutorials/managing-dependencies.rst:64 msgid "" -"``urls`` lets you list any number of extra links to show on PyPI. Generally " -"this could be to the source, documentation, issue trackers, etc." +"Pipenv manages dependencies on a per-project basis. To install packages, " +"change into your project's directory (or just an empty directory for this " +"tutorial) and run:" msgstr "" -"``urls`` には、 PyPI で表示するその他のリンクを幾つでも列挙しておくことができ" -"ます。一般的に、ソースコードや説明文書、課題追跡システムその他へのリンクを挙" -"げておけばよいでしょう。" +"Pipenv は、プロジェクト毎に依存関係を管理します。パッケージをインストールする" +"には、まずプロジェクト (このチュートリアル用にはからのディレクトリへ行けば十" +"分) のディレクトリへ行って、以下のコマンドを実行してください:" -#: ../source/tutorials/packaging-projects.rst:251 -#, fuzzy +#: ../source/tutorials/managing-dependencies.rst:73 msgid "" -"See the :ref:`pyproject.toml guide ` 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." +"Pipenv will install the `Requests`_ library and create a ``Pipfile`` for you " +"in your project's directory. The :ref:`Pipfile` is used to track which " +"dependencies your project needs in case you need to re-install them, such as " +"when you share your project with others. You should get output similar to " +"this (although the exact paths shown will vary):" msgstr "" -"``[project]`` テーブルに定義できるこれらのフィールドやその他のフィールドにつ" -"いての詳しい情報が必要であれば、 :ref:`プロジェクトにおけるメタデータの仕様 " -"` を見てください。他のよく使われるフィールドに" -"は、検索にかかりやすくするための ``keywords`` や、当該パッケージをインストー" -"ルするために必須のパッケージを示す ``dependencies`` があります。" +"Pipenv は、 `Requests`_ ライブラリをインストールし、プロジェクトのディレクト" +"リに ``Pipfile`` を作成するでしょう。 :ref:`Pipfile` は、そのプロジェクトを共" +"有している場合などのように、再インストールが必要な時にそのプロジェクトが必要" +"とする依存関係を追跡するために使われます。 (正確なディレクトリパスは変化する" +"としても) これに似た出力が表示されるべきです:" -#: ../source/tutorials/packaging-projects.rst:258 -msgid "Creating README.md" -msgstr "README.md を作成する" +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "インストール済みのパッケージを使う" -#: ../source/tutorials/packaging-projects.rst:260 +#: ../source/tutorials/managing-dependencies.rst:111 msgid "" -"Open :file:`README.md` and enter the following content. You can customize " -"this if you'd like." +"Now that Requests is installed you can create a simple :file:`main.py` file " +"to use it:" msgstr "" -":file:`README.md` を開いて、以下の内容を入力してください。そうしたければ、カ" -"スタマイズした内容でも構いません。" +"今や、Requests がインストールされたので、それを使うために単純な :file:`main." +"py` ファイルを作成しましょう:" -#: ../source/tutorials/packaging-projects.rst:273 -msgid "Creating a LICENSE" -msgstr "LICENSE ファイルを作成する" +#: ../source/tutorials/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "続いて ``pipenv run`` を使ってこのスクリプトを走らせます:" -#: ../source/tutorials/packaging-projects.rst:275 +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "大体こんな感じの出力が得られるはずです:" + +#: ../source/tutorials/managing-dependencies.rst:134 msgid "" -"It's important for every package uploaded to the Python Package Index to " -"include a license. This tells users who install your package the terms under " -"which they can use your package. For help picking a license, see https://" -"choosealicense.com/. Once you have chosen a license, open :file:`LICENSE` " -"and enter the license text. For example, if you had chosen the MIT license:" +"Using ``pipenv run`` ensures that your installed packages are available to " +"your script. It's also possible to spawn a new shell that ensures all " +"commands have access to your installed packages with ``pipenv shell``." msgstr "" -"Python パッケージインデックスにアップロードされた各々のパッケージにとって、ラ" -"イセンス条項を明示することは重要です。こうすることで、そのパッケージをインス" -"トールするユーザに対して、どのような条件のもとでそのパッケージを使うことがで" -"きるのかを伝えることができるからです。ライセンス選択の助けが必要ならば、 " -"https://choosealicense.com/ を見てください。どのライセンスにするか選択できた" -"ら、 :file:`LICENSE` ファイルを開いてそのライセンス条項を書き込んでください。" -"例えば、 MIT ライセンスを選択したなら次のようにします:" +"``pipenv run`` を使うことで、インストール済みのパッケージを確実にスクリプトか" +"ら利用できるようになります。``pipenv shell`` で新しいシェルを立ち上げれば、あ" +"らゆるコマンドからインストール済みパッケージへのアクセスが保証されます。" -#: ../source/tutorials/packaging-projects.rst:304 +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:504 +msgid "Next steps" +msgstr "次なる一歩" + +#: ../source/tutorials/managing-dependencies.rst:142 msgid "" -"Most build backends automatically include license files in packages. See " -"your backend's documentation for more details." +"Congratulations, you now know how to effectively manage dependencies and " +"development environments on a collaborative Python project! ✨ 🍰 ✨" msgstr "" -"ほとんどのビルドバックエンドは、パッケージ群のライセンスファイルを自動的に取" -"り込みます。詳細については、あなたが使うバックエンドの説明文書を見てくださ" -"い。" +"おめでとう、今やあなたは、共同作業を必要とする Python プロジェクトにおいて、" +"依存関係や開発環境を効率良く管理する方法をご存知です！✨ 🍰 ✨" -#: ../source/tutorials/packaging-projects.rst:309 -msgid "Including other files" -msgstr "その他のファイルを包含する" +#: ../source/tutorials/managing-dependencies.rst:145 +msgid "" +"If you're interested in creating and distributing your own Python packages, " +"see the :ref:`tutorial on packaging and distributing packages `." +msgstr "" +"自分で Python パッケージを作成したり配布したりすることに興味があるなら、 :" +"ref:`パッケージングとパッケージ配布のためのチュートリアル ` を見てください。" -#: ../source/tutorials/packaging-projects.rst:311 +#: ../source/tutorials/managing-dependencies.rst:148 msgid "" -"The files listed above will be included automatically in your :term:`source " -"distribution `. If you want to include " -"additional files, see the documentation for your build backend." +"Note that when your application includes definitions of Python source " +"packages, they (and their dependencies) can be added to your ``pipenv`` " +"environment with ``pipenv install -e `` " +"(e.g. ``pipenv install -e .`` or ``pipenv install -e src``)." msgstr "" -"上に挙げたファイル群は、 :term:`ソースコード配布物 ` に自動的に含まれるでしょう。他のファイルも含めておきたいなら、" -"使っているビルドバックエンドの説明文書を見てください。" +"あなたのアプリケーションが Python ソースコードパッケージの定義を含んでいる場" +"合には、 ``pipenv install -e `` (例えば " +"``pipenv install -e .`` や ``pipenv install -e src``) によって、 (その依存先" +"も含めて) それがあなたの ``pipenv`` 環境にインストールされ得ることに注意して" +"ください。" -#: ../source/tutorials/packaging-projects.rst:318 -msgid "Generating distribution archives" -msgstr "配布物アーカイブを生成する" +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "アプリケーションの依存関係管理のためのその他のツール" -#: ../source/tutorials/packaging-projects.rst:320 +#: ../source/tutorials/managing-dependencies.rst:159 msgid "" -"The next step is to generate :term:`distribution packages ` for the package. These are archives that are uploaded to the " -"Python Package Index and can be installed by :ref:`pip`." +"If you find this particular approach to managing application dependencies " +"isn't working well for you or your use case, you may want to explore these " +"other tools and techniques, listed in alphabetical order, to see if one of " +"them is a better fit:" msgstr "" -"次のステップでは、そのパッケージの :term:`配布物パッケージ ` を生成します。これらは、 Python パッケージインデックスへアップロー" -"ドされ、 :ref:`pip` でインストールされることができるものです。" +"アプリケーションの依存関係管理で、あなたのユースケースではこの特定のアプロー" +"チがあまりうまく働かないことがわかったならば、この後にアルファベット順に列挙" +"する他のツール群やテクニックがより上手く使えるかどうか試してみたくなるかもし" +"れません:" -#: ../source/tutorials/packaging-projects.rst:324 -msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +#: ../source/tutorials/managing-dependencies.rst:163 +msgid "" +"`hatch `_ for opinionated coverage of even " +"more steps in the project management workflow, such as incrementing versions " +"and creating new skeleton projects from project templates." msgstr "" -"PyPA の :ref:`build` の最新版がインストールされていることを確認してください:" +"`hatch `_ は、プロジェクト管理のワークフローに" +"おいて、バージョン番号の増やし方やテンプレートから新しいスケルトンプロジェク" +"トを作成するやり方など、ステップ数は増えてもこだわりのあるやり方でやろうとす" +"るツールです。" -#: ../source/tutorials/packaging-projects.rst:338 +#: ../source/tutorials/managing-dependencies.rst:166 msgid "" -"If you have trouble installing these, see the :doc:`installing-packages` " -"tutorial." +"`micropipenv `_ for a " +"lightweight wrapper around pip that supports ``requirements.txt``, Pipenv " +"and Poetry lock files, or converting them to pip-tools compatible output. " +"Designed for containerized Python applications, but not limited to them." msgstr "" -"これらをインストールするのに困難を感じるようなら、 :doc:`パッケージをインス" -"トールする ` チュートリアルを見てください。" +"`micropipenv `_ は、 pip に対す" +"る軽量のラッパで ``requirements.txt`` や Pipenv や Poetry のロックファイル、" +"あるいはそれらを pip ツールと互換性のある形への変換出力をサポートするツールで" +"す。コンテナ化された Python アプリケーションのために設計されましたが、用途は" +"それに限りません。" -#: ../source/tutorials/packaging-projects.rst:341 +#: ../source/tutorials/managing-dependencies.rst:170 msgid "" -"Now run this command from the same directory where :file:`pyproject.toml` is " -"located:" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." msgstr "" -"さて、 :file:`pyproject.toml` ファイルがあるのと同じディレクトリでこのコマン" -"ドを実行しましょう:" +"`PDM `_ は、 :pep:`517` や :pep:`621` の" +"ような標準に立脚した近代的な Python パッケージ管理ツールです。" -#: ../source/tutorials/packaging-projects.rst:355 +#: ../source/tutorials/managing-dependencies.rst:172 msgid "" -"This command should output a lot of text and once completed should generate " -"two files in the :file:`dist` directory:" +"`pip-tools `_ for creating a lock " +"file of all dependencies from a list of packages directly used in a project, " +"and ensuring that only those dependencies are installed." msgstr "" -"このコマンドから多くのテキストメッセージが出力されますが、実行が終われば :" -"file:`dist` ディレクトリにふたつのファイルが生成されていることでしょう:" +"`pip-tools `_ は、プロジェクト内で直接" +"使われているパッケージのリストから全ての依存関係のロックファイルを生成する" +"ツールで、依存関係に現れるものだけがインストールされていることを保証します。" -#: ../source/tutorials/packaging-projects.rst:365 +#: ../source/tutorials/managing-dependencies.rst:175 msgid "" -"The ``tar.gz`` file is a :term:`source distribution ` whereas the ``.whl`` file is a :term:`built distribution `. Newer :ref:`pip` versions preferentially install built " -"distributions, but will fall back to source distributions if needed. You " -"should always upload a source distribution and provide built distributions " -"for the platforms your project is compatible with. In this case, our example " -"package is compatible with Python on any platform so only one built " -"distribution is needed." +"`Poetry `__ for a tool comparable " +"in scope to Pipenv that focuses more directly on use cases where the project " +"being managed is structured as a distributable Python package with a valid " +"``pyproject.toml`` file. By contrast, Pipenv explicitly avoids making the " +"assumption that the application being worked on will support distribution as " +"a ``pip``-installable Python package." msgstr "" -"``tar.gz`` ファイルは :term:`ソースコード配布物 ` であり、 ``.whl`` ファイルは :term:`ビルド済配布物 ` です。新しめのバージョンの :ref:`pip` では、ビルド済配布物を優" -"先的にインストールしますが、必要であればソースコード配布物にフォールバックし" -"ます。ソースコード配布物については常にアップロードするべきであり、あなたのプ" -"ロジェクトが動作するはずのプラットフォーム向けのビルド済配布物についても準備" -"するべきです。我々の例示のためのパッケージはすべてのプラットフォーム上の " -"Python で動作するものなので、ビルド済配布物がひとつあれば十分です。" +"`Poetry `__ は、そのカバーする範囲と" +"いう点で Pipenv と互換性のあるツールで、 ``pyproject.toml`` ファイルを使った" +"配布可能な Python パッケージとしてプロジェクト管理のユースケースが構成されて" +"いる場合にもっと直接に使用することに焦点を当てたものです。これとは対照的に、 " +"Pipenv は明示的に、 (開発) 作業中のアプリケーションが ``pip`` でインストール" +"可能な Python パッケージとしての配布をサポートしているという仮定を置くことを" +"避けています。" -#: ../source/tutorials/packaging-projects.rst:374 -msgid "Uploading the distribution archives" -msgstr "配布物アーカイブをアップロードする" +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "Python のプロジェクトをパッケージングする" -#: ../source/tutorials/packaging-projects.rst:376 -msgid "Finally, it's time to upload your package to the Python Package Index!" +#: ../source/tutorials/packaging-projects.rst:4 +msgid "" +"This tutorial walks you through how to package a simple Python project. It " +"will show you how to add the necessary files and structure to create the " +"package, how to build the package, and how to upload it to the Python " +"Package Index (PyPI)." +msgstr "" +"このチュートリアルでは、簡単な Python プロジェクトをどのようにしてパッケージ" +"するのかについて、一通り見て回ります。パッケージを構成するために必要なファイ" +"ルやディレクトリを追加する方法や、パッケージをビルドする方法、そして、Python " +"パッケージインデックス (PyPI) にパッケージをアップロードする方法をお見せしま" +"す。" + +#: ../source/tutorials/packaging-projects.rst:10 +msgid "" +"If you have trouble running the commands in this tutorial, please copy the " +"command and its output, then `open an issue`_ on the `packaging-problems`_ " +"repository on GitHub. We'll do our best to help you!" msgstr "" -"ついにあなたのパッケージを Python パッケージインデックスへアップロードする時" -"が来ました！" +"このチュートリアルに出てくるコマンドを実行したら問題が発生したという場合に" +"は、コマンドと結果出力をコピーして、 GitHub の `packaging-problems`_ リポジト" +"リで `新たな課題 `_ を追加してください。我々が全力であなたをお" +"助けします！" -#: ../source/tutorials/packaging-projects.rst:378 +#: ../source/tutorials/packaging-projects.rst:18 msgid "" -"The first thing you'll need to do is register an account on TestPyPI, which " -"is a separate instance of the package index intended for testing and " -"experimentation. It's great for things like this tutorial where we don't " -"necessarily want to upload to the real index. To register an account, go to " -"https://test.pypi.org/account/register/ and complete the steps on that page. " -"You will also need to verify your email address before you're able to upload " -"any packages. For more details, see :doc:`/guides/using-testpypi`." +"Some of the commands require a newer version of :ref:`pip`, so start by " +"making sure you have the latest version installed:" msgstr "" -"最初に実行しなければならないことは、試験や実験の場となることを意図してパッ" -"ケージインデックスとは別のインスタンスとして立てられたインスタンスである " -"TestPyPI にアカウントを登録することです。このチュートリアルのように、必ずしも" -"実際のインデックスにアップロードしたいと思わない場合には、 (TestPI は) 最適で" -"す。アカウントを登録するためには、 https://test.pypi.org/account/register/ へ" -"行って、そのページにあるステップを完了してください。パッケージをアップロード" -"できるようになる前に、あなたの電子メールアドレスを検証することも必要になるで" -"しょう。もっと詳しいことが知りたければ、 :doc:`/guides/using-testpypi` を見て" -"ください。" +"コマンドの中のいくつかは新しめのバージョンの :ref:`pip` でないとだめなので、" +"最新版をインストールして使っていることを最初に確認しておいてください:" -#: ../source/tutorials/packaging-projects.rst:386 +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "単純なプロジェクト" + +#: ../source/tutorials/packaging-projects.rst:37 msgid "" -"To securely upload your project, you'll need a PyPI `API token`_. Create one " -"at https://test.pypi.org/manage/account/#api-tokens, setting the \"Scope\" " -"to \"Entire account\". **Don't close the page until you have copied and " -"saved the token — you won't see that token again.**" +"This tutorial uses a simple project named " +"``example_package_YOUR_USERNAME_HERE``. If your username is ``me``, then the " +"package would be ``example_package_me``; this ensures that you have a unique " +"package name that doesn't conflict with packages uploaded by other people " +"following this tutorial. We recommend following this tutorial as-is using " +"this project, before packaging your own project." msgstr "" -"あなたのプロジェクトを安全にアップロードするためには、 PyPI `API トークン`_ " -"が必要になるでしょう。 https://test.pypi.org/manage/account/#api-tokens で、 " -"\"スコープ\" として \"アカウント全体\" を指定して、ひとつ作成してください。 " -"**トークンをコピーして保存するまで、ページを閉じないでください — トークンは二" -"度と表示されません。**" +"このチュートリアルは、 ``example_package_YOUR_USERNAME_HERE`` という名前の単" +"純なプロジェクトを使っています。もしあなたのユーザ名が ``me`` であるなら、" +"パッケージの名前は ``example_package_me`` となるでしょう; こうすることで、こ" +"のチュートリアルに従っている他の人たちがアップロードするパッケージ群と名前が" +"衝突することのない一意なパッケージ名を使っていることを保証できます。自分自身" +"のプロジェクトのパッケージングを始める前に、このプロジェクト名を使ってこの" +"チュートリアルに沿った練習をすることをお勧めします。" -#: ../source/tutorials/packaging-projects.rst:393 +#: ../source/tutorials/packaging-projects.rst:44 +msgid "Create the following file structure locally:" +msgstr "ローカルに以下のファイル構造を作成する:" + +#: ../source/tutorials/packaging-projects.rst:54 msgid "" -"Now that you are registered, you can use :ref:`twine` to upload the " -"distribution packages. You'll need to install Twine:" +"The directory containing the Python files should match the project name. " +"This simplifies the configuration and is more obvious to users who install " +"the package." msgstr "" -"ユーザ登録が済んだら、 :ref:`twine` で配布物パッケージをアップロードすること" -"ができます。Twine のインストールが必要ならこのようにしてください:" +"Python ファイル群を格納するディレクトリは、プロジェクト名と同じ名前であるべき" +"です。こうすることで設定が簡単になり、また、パッケージをインストールするユー" +"ザから見てより明白になります。" -#: ../source/tutorials/packaging-projects.rst:408 +#: ../source/tutorials/packaging-projects.rst:57 +#, fuzzy msgid "" -"Once installed, run Twine to upload all of the archives under :file:`dist`:" +":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 " +"[#namespace-packages]_." msgstr "" -"インストールできたら、 :file:`dist` ディレクトリ内にあるアーカイブファイルを" -"すべてアップとーどしてください:" +"パッケージとしてのディレクトリをインポートするには :file:`__init__.py` が存在" +"していなければならず、また、それは空であるべきです。" -#: ../source/tutorials/packaging-projects.rst:422 +#: ../source/tutorials/packaging-projects.rst:60 msgid "" -"You will be prompted for a username and password. For the username, use " -"``__token__``. For the password, use the token value, including the ``pypi-" -"`` prefix." +":file:`example.py` is an example of a module within the package that could " +"contain the logic (functions, classes, constants, etc.) of your package. " +"Open that file and enter the following content:" msgstr "" -"ユーザ名とパスワードの入力を促されることでしょう。ユーザ名には ``__token__`` " -"を使ってください。パスワードには接頭子の ``pypi-`` を含めたトークンの値を使っ" -"てください。" +":file:`example.py` は、パッケージの中であなたのパッケージのロジック (関数・ク" +"ラス・定数・その他) を含むであろうモジュールの例です。このファイルを開いて、" +"以下の内容を入力してください:" -#: ../source/tutorials/packaging-projects.rst:426 -msgid "After the command completes, you should see output similar to this:" -msgstr "コマンド実行完了後、これに似た出力を見ることになるでしょう:" +#: ../source/tutorials/packaging-projects.rst:69 +msgid "" +"If you are unfamiliar with Python's :term:`modules ` and :term:" +"`import packages `, take a few minutes to read over the " +"`Python documentation for packages and modules`_." +msgstr "" +"Python における :term:`モジュール ` や :term:`パッケージのインポート " +"` に馴染みがなければ、数分を費やして `パッケージとモジュール" +"に関する Python の説明文書 `_ " +"を読み通してください。" -#: ../source/tutorials/packaging-projects.rst:437 +#: ../source/tutorials/packaging-projects.rst:73 msgid "" -"Once uploaded, your package should be viewable on TestPyPI; for example: " -"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +"Once you create this structure, you'll want to run all of the commands in " +"this tutorial within the ``packaging_tutorial`` directory." msgstr "" -"あなたのパッケージをアップロードしたら、 TestPyPI 上で閲覧できるようになりま" -"す; 例えば: ``https://test.pypi.org/project/" -"example_package_YOUR_USERNAME_HERE`` 。" +"この構造さえ作れば、このチュートリアルに出てくるすべてのコマンドを " +"``packaging_tutorial`` ディレクトリで実行したくなるでしょう。" -#: ../source/tutorials/packaging-projects.rst:442 -msgid "Installing your newly uploaded package" -msgstr "新しくアップロードしたあなたのパッケージをインストールする" +#: ../source/tutorials/packaging-projects.rst:81 +msgid "Creating the package files" +msgstr "パッケージファイルを作成する" -#: ../source/tutorials/packaging-projects.rst:444 +#: ../source/tutorials/packaging-projects.rst:83 msgid "" -"You can use :ref:`pip` to install your package and verify that it works. " -"Create a :ref:`virtual environment ` and install your package from TestPyPI:" +"You will now add files that are used to prepare the project for " +"distribution. When you're done, the project structure will look like this:" msgstr "" -":ref:`pip` を使えば、あなたのパッケージをインストールして動作を検証することが" -"できます。 :ref:`仮想環境 ` を作成し" -"て、 TestPyPI からあなたのパッケージをインストールしましょう:" +"ここで、プロジェクトの配布を準備するために使われるファイル群を追加しましょ" +"う。それが終わったら、プロジェクトの構造はこんな風になっていることでしょう:" -#: ../source/tutorials/packaging-projects.rst:460 -msgid "Make sure to specify your username in the package name!" -msgstr "パッケージ名の中にあなたのユーザ名を指定するのをお忘れなく！" +#: ../source/tutorials/packaging-projects.rst:101 +msgid "Creating a test directory" +msgstr "test ディレクトリを作成する" -#: ../source/tutorials/packaging-projects.rst:462 -msgid "" -"pip should install the package from TestPyPI and the output should look " -"something like this:" +#: ../source/tutorials/packaging-projects.rst:103 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." msgstr "" -"pip でパッケージを TestPyPI からインストールできるはずで、その出力は何か次の" -"ようなものに見えるでしょう:" +":file:`tests/` は、テスト用のファイルを置くためのプレースホルダーです。現段階" +"では、空のままにしておいてください。" -#: ../source/tutorials/packaging-projects.rst:472 -msgid "" -"This example uses ``--index-url`` flag to specify TestPyPI instead of live " -"PyPI. Additionally, it specifies ``--no-deps``. Since TestPyPI doesn't have " -"the same packages as the live PyPI, it's possible that attempting to install " -"dependencies may fail or install something unexpected. While our example " -"package doesn't have any dependencies, it's a good practice to avoid " -"installing dependencies when using TestPyPI." +#: ../source/tutorials/packaging-projects.rst:109 +msgid "Choosing a build backend" msgstr "" -"この例では ``--index-url`` フラグを使って本番環境である PyPI の代わりに " -"TestPyPI を指定しています。さらに、 ``--no-deps`` も指定しています。 " -"TestPyPI には本番環境である PyPI と同じだけのパッケージが存在しないので、依存" -"先となるパッケージを同時にインストールしようとしても、失敗するか、または、期" -"待していたものとは異なる何かをインストールしてしまう恐れがあります。我々の例" -"として使っているパッケージには依存先がないので、 TestPyPI を使う時には依存先" -"をインストールしないように指定しておくことは良いやり方です。" -#: ../source/tutorials/packaging-projects.rst:479 +#: ../source/tutorials/packaging-projects.rst:111 msgid "" -"You can test that it was installed correctly by importing the package. Make " -"sure you're still in your virtual environment, then run Python:" +"Tools like :ref:`pip` and :ref:`build` do not actually convert your sources " +"into a :term:`distribution package ` (like a wheel); " +"that job is performed by a :term:`build backend `. The build " +"backend determines how your project will specify its configuration, " +"including metadata (information about the project, for example, the name and " +"tags that are displayed on PyPI) and input files. Build backends have " +"different levels of functionality, such as whether they support building :" +"term:`extension modules `, and you should choose one that " +"suits your needs and preferences." msgstr "" -"パッケージをインポートしてみることで、正しくインストールされたかどうかを試験" -"することができます。まだ仮想環境内にいることを確認してから Python を走らせま" -"しょう:" - -#: ../source/tutorials/packaging-projects.rst:494 -msgid "and import the package:" -msgstr "そして、パッケージをインポートしましょう:" -#: ../source/tutorials/packaging-projects.rst:506 +#: ../source/tutorials/packaging-projects.rst:120 +#, fuzzy msgid "" -"**Congratulations, you've packaged and distributed a Python 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 `." msgstr "" -"**おめでとうございます、あなたは Python のプロジェクトをパッケージングし、配" -"布することができました！** ✨ 🍰 ✨" +":file:`pyproject.toml` は、 :ref:`pip` や :ref:`build` のような \"フロントエ" +"ンド\" のビルドツールに対して、どの \"backend\"を使ってそのプロジェクトの :" +"term:`配布パッケージ ` を作成するべきかを指定します。" +"バックエンドの選択肢は多数あります; このチュートリアルでは :ref:`Hatchling " +"` をデフォルトとして使っていますが、 :ref:`メタデータの設定 " +"` のための ``[project]`` テーブルをサポートしてさえいれ" +"ば :ref:`setuptools` ・ :ref:`Flit ` ・ :ref:`PDM ` やその他のツー" +"ルでも同じように動作することでしょう。" -#: ../source/tutorials/packaging-projects.rst:509 +#: ../source/tutorials/packaging-projects.rst:127 msgid "" -"Keep in mind that this tutorial showed you how to upload your package to " -"Test PyPI, which isn't a permanent storage. The Test system occasionally " -"deletes packages and accounts. It is best to use TestPyPI for testing and " -"experiments like this tutorial." +"Some build backends are part of larger tools that provide a command-line " +"interface with additional features like project initialization and version " +"management, as well as building, uploading, and installing packages. This " +"tutorial uses single-purpose tools that work independently." msgstr "" -"このチュートリアルではあなたのパッケージを Test PyPI に、つまり永続的なスト" -"レージではないところにアップロードする方法について示したということを忘れない" -"でください。テストシステムは、時折パッケージやアカウントを削除します。 Test " -"PyPI は、このチュートリアルのような試行や実験のために使うのがベストです。" +"ビルド・アップロード・インストールと並んでプロジェクト初期化やバージョン管理" +"のような追加機能を伴ったコマンドラインインタフェースを提供する、もっと大きな" +"ツールの一部を構成するビルドバックエンドもあります。このチュートリアルでは、" +"独立に動作する単一目的のツールを扱います。" -#: ../source/tutorials/packaging-projects.rst:514 +#: ../source/tutorials/packaging-projects.rst:132 msgid "" -"When you are ready to upload a real package to the Python Package Index you " -"can do much the same as you did in this tutorial, but with these important " -"differences:" +"The :file:`pyproject.toml` tells :term:`build frontend ` " +"tools like :ref:`pip` and :ref:`build` which backend to use for your " +"project. Below are some examples for common build backends, but check your " +"backend's own documentation for more details." msgstr "" -"実際のパッケージを Python パッケージインデックスへアップロードする準備ができ" -"たら、このチュートリアルでやったのと概ね同じことをやれば大丈夫ですが、次のよ" -"うな重要な違いがあります:" -#: ../source/tutorials/packaging-projects.rst:518 +#: ../source/tutorials/packaging-projects.rst:170 msgid "" -"Choose a memorable and unique name for your package. You don't have to " -"append your username as you did in the tutorial, but you can't use an " -"existing name." -msgstr "" -"あなたのパッケージ用に覚えやすくて独特な名前を付けましょう。チュートリアルで" -"やったようにあなたのユーザ名を追記する必要はありませんが、既存の名前は使えま" -"せん。" +"The ``requires`` key is a list of packages that are needed to build your " +"package. The :term:`frontend ` should install them " +"automatically when building your package. Frontends usually run builds in " +"isolated environments, so omitting dependencies here may cause build-time " +"errors. This should always include your backend's package, and might have " +"other build-time dependencies." +msgstr "" -#: ../source/tutorials/packaging-projects.rst:520 +#: ../source/tutorials/packaging-projects.rst:177 +#, fuzzy msgid "" -"Register an account on https://pypi.org - note that these are two separate " -"servers and the login details from the test server are not shared with the " -"main server." +"The ``build-backend`` key is the name of the Python object that frontends " +"will use to perform the build." msgstr "" -"https://pypi.org でアカウントを登録しましょう - これらはふたつの相異なるサー" -"バであって、テストサーバ側のログイン情報はメインサーバに共有されてはいませ" -"ん。" +"``build-backend`` は、そのフロントエンドがビルドを実行するにあたって使用する" +"であろう Python オブジェクトの名前です。" -#: ../source/tutorials/packaging-projects.rst:523 +#: ../source/tutorials/packaging-projects.rst:180 msgid "" -"Use ``twine upload dist/*`` to upload your package and enter your " -"credentials for the account you registered on the real PyPI. Now that " -"you're uploading the package in production, you don't need to specify ``--" -"repository``; the package will upload to https://pypi.org/ by default." +"Both of these values will be provided by the documentation for your build " +"backend, or generated by its command line interface. There should be no need " +"for you to customize these settings." msgstr "" -"あなたのパッケージをアップロードするのに ``twine upload dist/*`` を使い、本番" -"環境の PyPI で登録したアカウントの認証情報を入力しましょう。今回は出荷状態の" -"パッケージをアップロードしようとしているので、 ``--repository`` を指定する必" -"要はありません; 指定しないことでパッケージはデフォルトの https://pypi.org/ へ" -"アップロードされるでしょう。" -#: ../source/tutorials/packaging-projects.rst:527 +#: ../source/tutorials/packaging-projects.rst:184 msgid "" -"Install your package from the real PyPI using ``python3 -m pip install [your-" -"package]``." +"Additional configuration of the build tool will either be in a ``tool`` " +"section of the ``pyproject.toml``, or in a special file defined by the build " +"tool. For example, when using ``setuptools`` as your build backend, " +"additional configuration may be added to a ``setup.py`` or ``setup.cfg`` " +"file, and specifying ``setuptools.build_meta`` in your build allows the " +"tools to locate and use these automatically." msgstr "" -"``python3 -m pip install [your-package`` を使って、あなたのパッケージを本番環" -"境の PyPI からインストールしましょう。" -#: ../source/tutorials/packaging-projects.rst:529 +#: ../source/tutorials/packaging-projects.rst:194 +msgid "Configuring metadata" +msgstr "メタデータを設定する" + +#: ../source/tutorials/packaging-projects.rst:196 msgid "" -"At this point if you want to read more on packaging Python libraries here " -"are some things you can do:" +"Open :file:`pyproject.toml` and enter the following content. Change the " +"``name`` to include your username; this ensures that you have a unique " +"package name that doesn't conflict with packages uploaded by other people " +"following this tutorial." msgstr "" -"ここまで読み進めてきて、もっと Python でのパッケージングについて読みたいので" -"あれば、次のようなものがあります:" +":file:`pyproject.toml` を開いて、以下の内容を入力してください。 ``name`` の値" +"はあなたのユーザ名に書き換えてください; こうすることで、このチュートリアルを" +"履修している他の人たちがアップロードするパッケージと衝突を起こさない一意な" +"パッケージ名を使っていることを保証することができます。" -#: ../source/tutorials/packaging-projects.rst:532 +#: ../source/tutorials/packaging-projects.rst:222 msgid "" -"Read about advanced configuration for your chosen build backend: `Hatchling " -"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +"``name`` is the *distribution name* of your package. This can be any name as " +"long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also " +"must not already be taken on PyPI. **Be sure to update this with your " +"username** for this tutorial, as this ensures you won't try to upload a " +"package with the same name as one which already exists." msgstr "" +"``name`` は、あなたのパッケージの *配布物の名前* です。これは、文字・数字・ " +"``.`` ・ ``_`` ・ ``-`` だけで構成されている限りは、どんな名前でも構いませ" +"ん。また、 PyPI 上に既に存在するものであってはなりません。このチュートリアル" +"では、あなたのユーザ名を使って更新していることを **確実にしてください** 、と" +"いうのは、そうすることで、既存の名前と同じ名前のパッケージのアップロードを試" +"みることがないと保証できるからです。" -#: ../source/tutorials/packaging-projects.rst:536 +#: ../source/tutorials/packaging-projects.rst:227 +#, fuzzy 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." +"``version`` is the package version. (Some build backends allow it to be " +"specified another way, such as from a file or Git tag.)" msgstr "" +"``version`` は、パッケージのバージョン番号です。バージョン番号についてもっと" +"詳細に知りたい場合は、 :ref:`バージョン指定子 ` を見てく" +"ださい。ビルドバックエンドの中には、ファイルから、もしくは、 git のタグからの" +"ように、別の方法で指定することを許容するものもあります。" -#: ../source/tutorials/packaging-projects.rst:539 +#: ../source/tutorials/packaging-projects.rst:229 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`." +"``authors`` is used to identify the author of the package; you specify a " +"name and an email for each author. You can also list ``maintainers`` in the " +"same format." msgstr "" -":ref:`hatch` ・ :ref:`flit` ・ :ref:`pdm` ・ :ref:`poetry` のように、単一のコ" -"マンドラインインタフェースでプロジェクト管理もパッケージングもできるパッケー" -"ジングツールについて検討しましょう。" +"``authors`` は、パッケージの作者を識別するために使われます; 作者の一人一人に" +"ついて名前と電子メールアドレスを指定します。同じフォーマットで " +"``maintainers`` を列挙することもできます。" -#: ../source/tutorials/packaging-projects.rst:547 -msgid "Notes" +#: ../source/tutorials/packaging-projects.rst:232 +msgid "``description`` is a short, one-sentence summary of the package." +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:`pyproject." +"toml guide `." msgstr "" +"``readme`` は、パッケージに関する詳細な説明を含んだファイルへのパスです。 " +"PyPI 上のパッケージ詳細のページにこの内容が表示されます。この場合、説明の文言" +"は :file:`README.md` (これがよくあるパターンです) からロードされます。他に" +"も、 :ref:`プロジェクトのメタデータの仕様 ` に記" +"述されているもっと先進的なテーブル形式があります。" -#: ../source/tutorials/packaging-projects.rst:549 +#: ../source/tutorials/packaging-projects.rst:238 +#, fuzzy msgid "" -"Technically, you can also create Python packages without an ``__init__.py`` " -"file, but those are called :doc:`namespace packages ` and considered an **advanced topic** (not covered in " -"this tutorial). If you are only getting started with Python packaging, it is " -"recommended to stick with *regular packages* and ``__init__.py`` (even if " -"the file is empty)." +"``requires-python`` gives the versions of Python supported by your project. " +"An installer like :ref:`pip` will look back through older versions of " +"packages until it finds one that has a matching Python version." msgstr "" +"``requires-python`` は、そのプロジェクトがサポートしている Python のバージョ" +"ンを与えます。 :ref:`pip` のようなインストーラは、 Python バージョンが合致す" +"るものまでパッケージのバージョンを遡って探索します。" -#: ../source/discussions/package-formats.rst:5 -msgid "Package Formats" -msgstr "パッケージフォーマット" +#: ../source/tutorials/packaging-projects.rst:241 +msgid "" +"``classifiers`` gives the index and :ref:`pip` some additional metadata " +"about your package. In this case, the package is only compatible with Python " +"3, is licensed under the MIT license, and is OS-independent. You should " +"always include at least which version(s) of Python your package works on, " +"which license your package is available under, and which operating systems " +"your package will work on. For a complete list of classifiers, see https://" +"pypi.org/classifiers/." +msgstr "" +"``classifiers`` は、インデックスと :ref:`pip` に、そのパッケージに関する追加" +"的なメタデータをいくつか与えます。この場合には、当該パッケージは Python 3 で" +"のみ動作し、 MIT ライセンスの下に従うものであり、 OS には依らず独立のもので" +"す。どのバージョンの Python 上でそのパッケージが動作するのか、どのライセンス" +"に従うのか、どのオペレーティングシステムで動作するのかを示しておくことは、常" +"に最低限それだけはやるべきことです。 classifiers の完全なリストについては、 " +"https://pypi.org/classifiers/ を見てください。" -#: ../source/discussions/package-formats.rst:7 +#: ../source/tutorials/packaging-projects.rst:248 msgid "" -"This page discusses the file formats that are used to distribute Python " -"packages and the differences between them." +"``urls`` lets you list any number of extra links to show on PyPI. Generally " +"this could be to the source, documentation, issue trackers, etc." msgstr "" -"このページでは、 Python パッケージの配布に使われるファイルフォーマット群とそ" -"の相違点について議論します。" +"``urls`` には、 PyPI で表示するその他のリンクを幾つでも列挙しておくことができ" +"ます。一般的に、ソースコードや説明文書、課題追跡システムその他へのリンクを挙" +"げておけばよいでしょう。" -#: ../source/discussions/package-formats.rst:10 +#: ../source/tutorials/packaging-projects.rst:251 +#, fuzzy msgid "" -"You will find files in two formats on package indices such as PyPI_: " -"**source distributions**, or **sdists** for short, and **binary " -"distributions**, commonly called **wheels**. For example, the `PyPI page " -"for pip 23.3.1 `_ lets you download two files, ``pip-23.3.1.tar." -"gz`` and ``pip-23.3.1-py3-none-any.whl``. The former is an sdist, the " -"latter is a wheel. As explained below, these serve different purposes. When " -"publishing a package on PyPI (or elsewhere), you should always upload both " -"an sdist and one or more wheel." +"See the :ref:`pyproject.toml guide ` 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." msgstr "" -"PyPI_ のようなパッケージインデックス上には、２種類のフォーマットが見つかるこ" -"とでしょう: **ソースコード配布物 ** 、短縮形で " -"**sdists**と呼ばれるものと **バイナリ配布物 ** 、" -"普通は **wheels** を呼ばれるものです。例えば、 `pip 23.3.1 用の PyPI ページ " -"`_ では、 ``pip-23.3.1.tar.gz`` と ``pip-23.3.1-py3-none-any.whl``" -" の二つのファイルをダウンロードすることができます。前者は sdist であり、" -"後者は wheel " -"です。下で説明するように、これらは異なった目的のために提供されています。 " -"PyPI (にせよ他のどこかにせよ) パッケージを公開する時は、常に sdist " -"とひとつまたは複数の wheel の両方をアップロードするべきです。" +"``[project]`` テーブルに定義できるこれらのフィールドやその他のフィールドにつ" +"いての詳しい情報が必要であれば、 :ref:`プロジェクトにおけるメタデータの仕様 " +"` を見てください。他のよく使われるフィールドに" +"は、検索にかかりやすくするための ``keywords`` や、当該パッケージをインストー" +"ルするために必須のパッケージを示す ``dependencies`` があります。" -#: ../source/discussions/package-formats.rst:21 -msgid "What is a source distribution?" -msgstr "ソースコード配布物とは何か？" +#: ../source/tutorials/packaging-projects.rst:258 +msgid "Creating README.md" +msgstr "README.md を作成する" -#: ../source/discussions/package-formats.rst:23 +#: ../source/tutorials/packaging-projects.rst:260 msgid "" -"Conceptually, a source distribution is an archive of the source code in raw " -"form. Concretely, an sdist is a ``.tar.gz`` archive containing the source " -"code plus an additional special file called ``PKG-INFO``, which holds the " -"project metadata. The presence of this file helps packaging tools to be more " -"efficient by not needing to compute the metadata themselves. The ``PKG-" -"INFO`` file follows the format specified in :ref:`core-metadata` and is not " -"intended to be written by hand [#core-metadata-format]_." +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." msgstr "" -"概念としては、ソースコード配布物は生の形のソースコードをアーカイブしたもので" -"す。具体的に言うと、sdist は、ソースコードに加えて、" -"プロジェクトのメタデータを保持する ``PKG-INFO`` " -"と言う名の特別なファイルをアーカイブした ``.tar.gz`` ファイルです。このファイ" -"ルの存在によってメタデータを自分自身で計算しなくても済むようにすることでパッ" -"ケージングツール群を補助しています。 ``PKG-INFO`` ファイルは、 :ref:`" -"コアとなるメタデータ ` で指定されたフォーマットに従うもので、" -"人の手で書くことが想定されていないものです [#core-metadata-format]_ 。" +":file:`README.md` を開いて、以下の内容を入力してください。そうしたければ、カ" +"スタマイズした内容でも構いません。" -#: ../source/discussions/package-formats.rst:31 +#: ../source/tutorials/packaging-projects.rst:273 +msgid "Creating a LICENSE" +msgstr "LICENSE ファイルを作成する" + +#: ../source/tutorials/packaging-projects.rst:275 msgid "" -"You can thus inspect the contents of an sdist by unpacking it using standard " -"tools to work with tar archives, such as ``tar -xvf`` on UNIX platforms " -"(like Linux and macOS), or :ref:`the command line interface of Python's " -"tarfile module ` on any platform." +"It's important for every package uploaded to the Python Package Index to " +"include a license. This tells users who install your package the terms under " +"which they can use your package. For help picking a license, see https://" +"choosealicense.com/. Once you have chosen a license, open :file:`LICENSE` " +"and enter the license text. For example, if you had chosen the MIT license:" msgstr "" -"従って、tar アーカイブを扱える標準的なツール、例えば UNIX プラットフォーム (" -"Linux や macOS) 上の ``tar -xvf`` や任意のプラットフォーム上の :ref:`Python " -"の tarfile モジュールのコマンドラインインターフェース ` を使ってアンパックすることで、ある sdist " -"の内容を検査することができます。" +"Python パッケージインデックスにアップロードされた各々のパッケージにとって、ラ" +"イセンス条項を明示することは重要です。こうすることで、そのパッケージをインス" +"トールするユーザに対して、どのような条件のもとでそのパッケージを使うことがで" +"きるのかを伝えることができるからです。ライセンス選択の助けが必要ならば、 " +"https://choosealicense.com/ を見てください。どのライセンスにするか選択できた" +"ら、 :file:`LICENSE` ファイルを開いてそのライセンス条項を書き込んでください。" +"例えば、 MIT ライセンスを選択したなら次のようにします:" -#: ../source/discussions/package-formats.rst:36 +#: ../source/tutorials/packaging-projects.rst:304 msgid "" -"Sdists serve several purposes in the packaging ecosystem. When :ref:`pip`, " -"the standard Python package installer, cannot find a wheel to install, it " -"will fall back on downloading a source distribution, compiling a wheel from " -"it, and installing the wheel. Furthermore, sdists are often used as the " -"package source by downstream packagers (such as Linux distributions, Conda, " -"Homebrew and MacPorts on macOS, ...), who, for various reasons, may prefer " -"them over, e.g., pulling from a Git repository." +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details." msgstr "" -"sdist " -"は、パッケージングのエコシステムの中でいくつかの目的のために使用されます。" -"Python パッケージインストーラの標準である :ref:`pip` がインストールするべき " -"wheel を見つけられない時にソースコード配布物をダウンロードしてそこから wheel " -"をコンパイルし、その wheel " -"をインストールするようにフォールバックすることでしょう。さらに、" -"さまざまな理由で例えば Git リポジトリからプルすることなどよりも (sdist を) " -"好むダウンストリームパッケージ (Linux ディストリビューション、 Conda 、 " -"macOS 上の Homebrew や MacPorts など ...)" -"にとってのパッケージソースとしてしばしば sdist が使われます。" +"ほとんどのビルドバックエンドは、パッケージ群のライセンスファイルを自動的に取" +"り込みます。詳細については、あなたが使うバックエンドの説明文書を見てくださ" +"い。" -#: ../source/discussions/package-formats.rst:44 +#: ../source/tutorials/packaging-projects.rst:309 +msgid "Including other files" +msgstr "その他のファイルを包含する" + +#: ../source/tutorials/packaging-projects.rst:311 msgid "" -"A source distribution is recognized by its file name, which has the form :" -"samp:`{package_name}-{version}.tar.gz`, e.g., ``pip-23.3.1.tar.gz``." +"The files listed above will be included automatically in your :term:`source " +"distribution `. If you want to include " +"additional files, see the documentation for your build backend." msgstr "" -"ソースコード配布物は、 :samp:`{package_name}-{version}.tar.gz` の形、例えば " -"``pip-23.3.1.tar.gz`` のファイル名で識別されます。" +"上に挙げたファイル群は、 :term:`ソースコード配布物 ` に自動的に含まれるでしょう。他のファイルも含めておきたいなら、" +"使っているビルドバックエンドの説明文書を見てください。" -#: ../source/discussions/package-formats.rst:50 +#: ../source/tutorials/packaging-projects.rst:318 +msgid "Generating distribution archives" +msgstr "配布物アーカイブを生成する" + +#: ../source/tutorials/packaging-projects.rst:320 msgid "" -"If you want technical details on the sdist format, read the :ref:`sdist " -"specification `." +"The next step is to generate :term:`distribution packages ` for the package. These are archives that are uploaded to the " +"Python Package Index and can be installed by :ref:`pip`." msgstr "" -"sdist 形式の技術的な詳細を知りたければ、 :ref:`sdist 仕様 ` を見てください。" +"次のステップでは、そのパッケージの :term:`配布物パッケージ ` を生成します。これらは、 Python パッケージインデックスへアップロー" +"ドされ、 :ref:`pip` でインストールされることができるものです。" -#: ../source/discussions/package-formats.rst:55 -msgid "What is a wheel?" -msgstr "wheel とは何か？" +#: ../source/tutorials/packaging-projects.rst:324 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" +"PyPA の :ref:`build` の最新版がインストールされていることを確認してください:" -#: ../source/discussions/package-formats.rst:57 +#: ../source/tutorials/packaging-projects.rst:338 msgid "" -"Conceptually, a wheel contains exactly the files that need to be copied when " -"installing the package." -msgstr "概念としては、 wheel は、パッケージをインストールする際にコピーされる必要のあ" -"るファイル群をそのまま含んでいるものです。" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" +"これらをインストールするのに困難を感じるようなら、 :doc:`パッケージをインス" +"トールする ` チュートリアルを見てください。" -#: ../source/discussions/package-formats.rst:60 +#: ../source/tutorials/packaging-projects.rst:341 msgid "" -"There is a big difference between sdists and wheels for packages with :term:" -"`extension modules `, written in compiled languages like " -"C, C++ and Rust, which need to be compiled into platform-dependent machine " -"code. With these packages, wheels do not contain source code (like C source " -"files) but compiled, executable code (like ``.so`` files on Linux or DLLs on " -"Windows)." +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" msgstr "" -"プラットフォームに依存した機械語にコンパイルする必要がある C や C++ や Rust " -"のようなコンパイル言語で書かれた :term:`拡張モジュール ` " -"を伴うパッケージにおいては、sdist と wheel " -"の間には大きな違いがあります。このようなパッケージでは、 wheel は " -"(C言語のソースのような) ソースコードを内包しておらず、代わりに (Linux " -"における ``.so`` ファイルや Windows における DLL のような) " -"コンパイル済みで実行可能なコードを含んでいます。" +"さて、 :file:`pyproject.toml` ファイルがあるのと同じディレクトリでこのコマン" +"ドを実行しましょう:" -#: ../source/discussions/package-formats.rst:66 +#: ../source/tutorials/packaging-projects.rst:355 msgid "" -"Furthermore, while there is only one sdist per version of a project, there " -"may be many wheels. Again, this is most relevant in the context of extension " -"modules. The compiled code of an extension module is tied to an operating " -"system and processor architecture, and often also to the version of the " -"Python interpreter (unless the :ref:`Python stable ABI ` " -"is used)." +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" msgstr "" -"さらにまた、あるバージョンのプロジェクトには sdist " -"がひとつしか存在しない一方で、wheel はたくさんあるかもしれません。繰り返しに" -"なりますが、これは拡張モジュールの文脈でもっとも有りがちなことです。拡張モジ" -"ュールのコンパイル済みのコードはオペレーティングシステムとプロセッサーアーキ" -"テクチャに、また、 (:ref:`Python stable ABI ` " -"を使っていなければ) しばしば Python " -"インタープリタのバージョンに紐付いています。" +"このコマンドから多くのテキストメッセージが出力されますが、実行が終われば :" +"file:`dist` ディレクトリにふたつのファイルが生成されていることでしょう:" -#: ../source/discussions/package-formats.rst:72 +#: ../source/tutorials/packaging-projects.rst:365 msgid "" -"For pure-Python packages, the difference between sdists and wheels is less " -"marked. There is normally one single wheel, for all platforms and Python " -"versions. Python is an interpreted language, which does not need ahead-of-" -"time compilation, so wheels contain ``.py`` files just like sdists." +"The ``tar.gz`` file is a :term:`source distribution ` whereas the ``.whl`` file is a :term:`built distribution `. Newer :ref:`pip` versions preferentially install built " +"distributions, but will fall back to source distributions if needed. You " +"should always upload a source distribution and provide built distributions " +"for the platforms your project is compatible with. In this case, our example " +"package is compatible with Python on any platform so only one built " +"distribution is needed." msgstr "" -"純 Python のパッケージでは、 sdist と wheel " -"の差異はあまり顕著ではありません。普通は、あらゆるプラットフォームと Python " -"のバージョン向けに wheel がたったひとつ存在します。 Python " -"はインタープリタ言語であり、事前にコンパイルしておく必要がなく、それゆえに " -"wheel は sdist と同様に ``.py`` ファイル群を内包しているのです。" +"``tar.gz`` ファイルは :term:`ソースコード配布物 ` であり、 ``.whl`` ファイルは :term:`ビルド済配布物 ` です。新しめのバージョンの :ref:`pip` では、ビルド済配布物を優" +"先的にインストールしますが、必要であればソースコード配布物にフォールバックし" +"ます。ソースコード配布物については常にアップロードするべきであり、あなたのプ" +"ロジェクトが動作するはずのプラットフォーム向けのビルド済配布物についても準備" +"するべきです。我々の例示のためのパッケージはすべてのプラットフォーム上の " +"Python で動作するものなので、ビルド済配布物がひとつあれば十分です。" -#: ../source/discussions/package-formats.rst:77 -msgid "" -"If you are wondering about ``.pyc`` bytecode files: they are not included in " -"wheels, since they are cheap to generate, and including them would " -"unnecessarily force a huge number of packages to distribute one wheel per " -"Python version instead of one single wheel. Instead, installers like :ref:" -"`pip` generate them while installing the package." +#: ../source/tutorials/packaging-projects.rst:374 +msgid "Uploading the distribution archives" +msgstr "配布物アーカイブをアップロードする" + +#: ../source/tutorials/packaging-projects.rst:376 +msgid "Finally, it's time to upload your package to the Python Package Index!" msgstr "" -"``.pyc`` バイトコードファイル群: これらは wheel には含まれていませんが、これ" -"らについて不思議に思っているなら、これらは安価に生成することができ、また、も" -"しこれをパッケージに含めるとすれば、単一の wheel を配布する代わりに、Python " -"のバージョン毎に巨大な数のパッケージを配布するという不必要なことを強いられる" -"ことになるでしょう。代わりに、 :ref:`pip` " -"のようなインストーラがインストール中に生成しています。" +"ついにあなたのパッケージを Python パッケージインデックスへアップロードする時" +"が来ました！" -#: ../source/discussions/package-formats.rst:83 +#: ../source/tutorials/packaging-projects.rst:378 msgid "" -"With that being said, there are still important differences between sdists " -"and wheels, even for pure Python projects. Wheels are meant to contain " -"exactly what is to be installed, and nothing more. In particular, wheels " -"should never include tests and documentation, while sdists commonly do. " -"Also, the wheel format is more complex than sdist. For example, it includes " -"a special file -- called ``RECORD`` -- that lists all files in the wheel " -"along with a hash of their content, as a safety check of the download's " -"integrity." +"The first thing you'll need to do is register an account on TestPyPI, which " +"is a separate instance of the package index intended for testing and " +"experimentation. It's great for things like this tutorial where we don't " +"necessarily want to upload to the real index. To register an account, go to " +"https://test.pypi.org/account/register/ and complete the steps on that page. " +"You will also need to verify your email address before you're able to upload " +"any packages. For more details, see :doc:`/guides/using-testpypi`." msgstr "" +"最初に実行しなければならないことは、試験や実験の場となることを意図してパッ" +"ケージインデックスとは別のインスタンスとして立てられたインスタンスである " +"TestPyPI にアカウントを登録することです。このチュートリアルのように、必ずしも" +"実際のインデックスにアップロードしたいと思わない場合には、 (TestPI は) 最適で" +"す。アカウントを登録するためには、 https://test.pypi.org/account/register/ へ" +"行って、そのページにあるステップを完了してください。パッケージをアップロード" +"できるようになる前に、あなたの電子メールアドレスを検証することも必要になるで" +"しょう。もっと詳しいことが知りたければ、 :doc:`/guides/using-testpypi` を見て" +"ください。" -#: ../source/discussions/package-formats.rst:91 +#: ../source/tutorials/packaging-projects.rst:386 msgid "" -"At a glance, you might wonder if wheels are really needed for \"plain and " -"basic\" pure Python projects. Keep in mind that due to the flexibility of " -"sdists, installers like pip cannot install from sdists directly -- they need " -"to first build a wheel, by invoking the :term:`build backend` that the sdist " -"specifies (the build backend may do all sorts of transformations while " -"building the wheel, such as compiling C extensions). For this reason, even " -"for a pure Python project, you should always upload *both* an sdist and a " -"wheel to PyPI or other package indices. This makes installation much faster " -"for your users, since a wheel is directly installable. By only including " -"files that must be installed, wheels also make for smaller downloads." +"To securely upload your project, you'll need a PyPI `API token`_. Create one " +"at https://test.pypi.org/manage/account/#api-tokens, setting the \"Scope\" " +"to \"Entire account\". **Don't close the page until you have copied and " +"saved the token — you won't see that token again.**" msgstr "" +"あなたのプロジェクトを安全にアップロードするためには、 PyPI `API トークン`_ " +"が必要になるでしょう。 https://test.pypi.org/manage/account/#api-tokens で、 " +"\"スコープ\" として \"アカウント全体\" を指定して、ひとつ作成してください。 " +"**トークンをコピーして保存するまで、ページを閉じないでください — トークンは二" +"度と表示されません。**" -#: ../source/discussions/package-formats.rst:102 +#: ../source/tutorials/packaging-projects.rst:393 msgid "" -"On the technical level, a wheel is a ZIP archive (unlike sdists which are " -"TAR archives). You can inspect its contents by unpacking it as a normal ZIP " -"archive, e.g., using ``unzip`` on UNIX platforms like Linux and macOS, " -"``Expand-Archive`` in Powershell on Windows, or :ref:`the command line " -"interface of Python's zipfile module `. This can " -"be very useful to check that the wheel includes all the files you need it to." +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" msgstr "" +"ユーザ登録が済んだら、 :ref:`twine` で配布物パッケージをアップロードすること" +"ができます。Twine のインストールが必要ならこのようにしてください:" -#: ../source/discussions/package-formats.rst:109 +#: ../source/tutorials/packaging-projects.rst:408 msgid "" -"Inside a wheel, you will find the package's files, plus an additional " -"directory called :samp:`{package_name}-{version}.dist-info`. This directory " -"contains various files, including a ``METADATA`` file which is the " -"equivalent of ``PKG-INFO`` in sdists, as well as ``RECORD``. This can be " -"useful to ensure no files are missing from your wheels." +"Once installed, run Twine to upload all of the archives under :file:`dist`:" msgstr "" +"インストールできたら、 :file:`dist` ディレクトリ内にあるアーカイブファイルを" +"すべてアップとーどしてください:" -#: ../source/discussions/package-formats.rst:115 +#: ../source/tutorials/packaging-projects.rst:422 msgid "" -"The file name of a wheel (ignoring some rarely used features) looks like " -"this: :samp:`{package_name}-{version}-{python_tag}-{abi_tag}-{platform_tag}." -"whl`. This naming convention identifies which platforms and Python versions " -"the wheel is compatible with. For example, the name ``pip-23.3.1-py3-none-" -"any.whl`` means that:" +"You will be prompted for a username and password. For the username, use " +"``__token__``. For the password, use the token value, including the ``pypi-" +"`` prefix." msgstr "" +"ユーザ名とパスワードの入力を促されることでしょう。ユーザ名には ``__token__`` " +"を使ってください。パスワードには接頭子の ``pypi-`` を含めたトークンの値を使っ" +"てください。" -#: ../source/discussions/package-formats.rst:121 +#: ../source/tutorials/packaging-projects.rst:426 +msgid "After the command completes, you should see output similar to this:" +msgstr "コマンド実行完了後、これに似た出力を見ることになるでしょう:" + +#: ../source/tutorials/packaging-projects.rst:437 msgid "" -"(``py3``) This wheel can be installed on any implementation of Python 3, " -"whether CPython, the most widely used Python implementation, or an " -"alternative implementation like PyPy_;" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." msgstr "" +"あなたのパッケージをアップロードしたら、 TestPyPI 上で閲覧できるようになりま" +"す; 例えば: ``https://test.pypi.org/project/" +"example_package_YOUR_USERNAME_HERE`` 。" -#: ../source/discussions/package-formats.rst:124 -msgid "(``none``) It does not depend on the Python version;" -msgstr "" +#: ../source/tutorials/packaging-projects.rst:442 +msgid "Installing your newly uploaded package" +msgstr "新しくアップロードしたあなたのパッケージをインストールする" -#: ../source/discussions/package-formats.rst:125 -msgid "(``any``) It does not depend on the platform." +#: ../source/tutorials/packaging-projects.rst:444 +msgid "" +"You can use :ref:`pip` to install your package and verify that it works. " +"Create a :ref:`virtual environment ` and install your package from TestPyPI:" msgstr "" +":ref:`pip` を使えば、あなたのパッケージをインストールして動作を検証することが" +"できます。 :ref:`仮想環境 ` を作成し" +"て、 TestPyPI からあなたのパッケージをインストールしましょう:" -#: ../source/discussions/package-formats.rst:127 +#: ../source/tutorials/packaging-projects.rst:460 +msgid "Make sure to specify your username in the package name!" +msgstr "パッケージ名の中にあなたのユーザ名を指定するのをお忘れなく！" + +#: ../source/tutorials/packaging-projects.rst:462 msgid "" -"The pattern ``py3-none-any`` is common for pure Python projects. Packages " -"with extension modules typically ship multiple wheels with more complex tags." +"pip should install the package from TestPyPI and the output should look " +"something like this:" msgstr "" +"pip でパッケージを TestPyPI からインストールできるはずで、その出力は何か次の" +"ようなものに見えるでしょう:" -#: ../source/discussions/package-formats.rst:130 +#: ../source/tutorials/packaging-projects.rst:472 msgid "" -"All technical details on the wheel format can be found in the :ref:`wheel " -"specification `." +"This example uses ``--index-url`` flag to specify TestPyPI instead of live " +"PyPI. Additionally, it specifies ``--no-deps``. Since TestPyPI doesn't have " +"the same packages as the live PyPI, it's possible that attempting to install " +"dependencies may fail or install something unexpected. While our example " +"package doesn't have any dependencies, it's a good practice to avoid " +"installing dependencies when using TestPyPI." msgstr "" +"この例では ``--index-url`` フラグを使って本番環境である PyPI の代わりに " +"TestPyPI を指定しています。さらに、 ``--no-deps`` も指定しています。 " +"TestPyPI には本番環境である PyPI と同じだけのパッケージが存在しないので、依存" +"先となるパッケージを同時にインストールしようとしても、失敗するか、または、期" +"待していたものとは異なる何かをインストールしてしまう恐れがあります。我々の例" +"として使っているパッケージには依存先がないので、 TestPyPI を使う時には依存先" +"をインストールしないように指定しておくことは良いやり方です。" -#: ../source/discussions/package-formats.rst:138 -#, fuzzy -msgid "What about eggs?" -msgstr "これは何..." - -#: ../source/discussions/package-formats.rst:140 +#: ../source/tutorials/packaging-projects.rst:479 msgid "" -"\"Egg\" is an old package format that has been replaced with the wheel " -"format. It should not be used anymore. Since August 2023, PyPI `rejects egg " -"uploads `_." +"You can test that it was installed correctly by importing the package. Make " +"sure you're still in your virtual environment, then run Python:" msgstr "" +"パッケージをインポートしてみることで、正しくインストールされたかどうかを試験" +"することができます。まだ仮想環境内にいることを確認してから Python を走らせま" +"しょう:" -#: ../source/discussions/package-formats.rst:144 -#, fuzzy -msgid "Here's a breakdown of the important differences between wheel and egg." -msgstr ":term:`Wheel`と :term:`Egg`の重要な差異について以下にまとめます。" +#: ../source/tutorials/packaging-projects.rst:494 +msgid "and import the package:" +msgstr "そして、パッケージをインポートしましょう:" -#: ../source/discussions/package-formats.rst:146 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:506 msgid "" -"The egg format was introduced by :ref:`setuptools` in 2004, whereas the " -"wheel format was introduced by :pep:`427` in 2012." +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" msgstr "" -":term:`Egg`のフォーマットは、2004年に:ref:`setuptools`によって、また、:term:" -"`Wheel`のフォーマットは2012年に:pep:`427`によって導入されました。" +"**おめでとうございます、あなたは Python のプロジェクトをパッケージングし、配" +"布することができました！** ✨ 🍰 ✨" -#: ../source/discussions/package-formats.rst:149 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:509 msgid "" -"Wheel has an :doc:`official standard specification `. Egg did not." +"Keep in mind that this tutorial showed you how to upload your package to " +"Test PyPI, which isn't a permanent storage. The Test system occasionally " +"deletes packages and accounts. It is best to use TestPyPI for testing and " +"experiments like this tutorial." msgstr "" -":term:`Wheel`には :doc:`公式の標準仕様 ` が存在します。 :term:`Egg`には対応するPEPがありません。" +"このチュートリアルではあなたのパッケージを Test PyPI に、つまり永続的なスト" +"レージではないところにアップロードする方法について示したということを忘れない" +"でください。テストシステムは、時折パッケージやアカウントを削除します。 Test " +"PyPI は、このチュートリアルのような試行や実験のために使うのがベストです。" -#: ../source/discussions/package-formats.rst:152 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:514 msgid "" -"Wheel is a :term:`distribution ` format, i.e a " -"packaging format. [#wheel-importable]_ Egg was both a distribution format " -"and a runtime installation format (if left zipped), and was designed to be " -"importable." +"When you are ready to upload a real package to the Python Package Index you " +"can do much the same as you did in this tutorial, but with these important " +"differences:" msgstr "" -":term:`Wheel`は :term:`配布物 `のフォーマット、つまり、" -"パッケージのフォーマットです。[1]_ :term:`Egg`は配布物のフォーマットでもあ" -"り、かつ、(もし圧縮されたままであれば)実行時のインストールフォーマットであっ" -"てimportができるように設計されています。" +"実際のパッケージを Python パッケージインデックスへアップロードする準備ができ" +"たら、このチュートリアルでやったのと概ね同じことをやれば大丈夫ですが、次のよ" +"うな重要な違いがあります:" -#: ../source/discussions/package-formats.rst:156 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:518 msgid "" -"Wheel archives do not include ``.pyc`` files. Therefore, when the " -"distribution only contains Python files (i.e. no compiled extensions), and " -"is compatible with Python 2 and 3, it's possible for a wheel to be " -"\"universal\", similar to an :term:`sdist `." +"Choose a memorable and unique name for your package. You don't have to " +"append your username as you did in the tutorial, but you can't use an " +"existing name." msgstr "" -":term:`Wheel`形式のファイルには.pycファイルが含まれていません。従って、配布物" -"には(コンパイル済のファイル抜きの)Pythonファイルのみ(含み、Pythonのバージョン" -"2と3で使用可能ですので、 :term:`sdist `と" -"同様にwheelは「汎用」であると言うことができます。" +"あなたのパッケージ用に覚えやすくて独特な名前を付けましょう。チュートリアルで" +"やったようにあなたのユーザ名を追記する必要はありませんが、既存の名前は使えま" +"せん。" -#: ../source/discussions/package-formats.rst:161 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:520 msgid "" -"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +"Register an account on https://pypi.org - note that these are two separate " +"servers and the login details from the test server are not shared with the " +"main server." msgstr "" -":term:`Wheel`は :pep:`PEP376-compliant <376>`に従って ``.dist-info`` ディレク" -"トリを用います。Eggは ``.egg-info`` を用います。" +"https://pypi.org でアカウントを登録しましょう - これらはふたつの相異なるサー" +"バであって、テストサーバ側のログイン情報はメインサーバに共有されてはいませ" +"ん。" -#: ../source/discussions/package-formats.rst:164 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:523 msgid "" -"Wheel has a :ref:`richer file naming convention `. A " -"single wheel archive can indicate its compatibility with a number of Python " -"language versions and implementations, ABIs, and system architectures." +"Use ``twine upload dist/*`` to upload your package and enter your " +"credentials for the account you registered on the real PyPI. Now that " +"you're uploading the package in production, you don't need to specify ``--" +"repository``; the package will upload to https://pypi.org/ by default." msgstr "" -":term:`Wheel`には:pep:`richer file naming convention <425>`が存在します。単独" -"のwheelアーカイブはPython言語のバージョンや実装、ABI、そしてシステムのアーキ" -"テクチャとの互換性を表示することができます。" +"あなたのパッケージをアップロードするのに ``twine upload dist/*`` を使い、本番" +"環境の PyPI で登録したアカウントの認証情報を入力しましょう。今回は出荷状態の" +"パッケージをアップロードしようとしているので、 ``--repository`` を指定する必" +"要はありません; 指定しないことでパッケージはデフォルトの https://pypi.org/ へ" +"アップロードされるでしょう。" -#: ../source/discussions/package-formats.rst:168 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:527 msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it." +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." msgstr "" -":term:`Wheel`はバージョン付けされています。それぞれのwheelファイルは、それを" -"パッケージしたwheelの仕様や実装のバージョンを保持しています。" +"``python3 -m pip install [your-package`` を使って、あなたのパッケージを本番環" +"境の PyPI からインストールしましょう。" -#: ../source/discussions/package-formats.rst:171 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:529 msgid "" -"Wheel is internally organized by `sysconfig path type `_, therefore making it " -"easier to convert to other formats." +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" msgstr "" -":term:`Wheel`は内部では`sysconfigパスの型 `_で整理されているので、他のフォーマットに" -"変換するのがより簡単になっています。" +"ここまで読み進めてきて、もっと Python でのパッケージングについて読みたいので" +"あれば、次のようなものがあります:" -#: ../source/discussions/package-formats.rst:177 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"This format is email-based. Although this would be unlikely to be chosen " -"today, backwards compatibility considerations lead to it being kept as the " -"canonical format. From the user point of view, this is mostly invisible, " -"since the metadata is specified by the user in a way understood by the build " -"backend, typically ``[project]`` in ``pyproject.toml``, and translated by " -"the build backend into ``PKG-INFO``." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/glossary.rst:47 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"A :term:`Distribution ` format containing files and " -"metadata that only need to be moved to the correct location on the target " -"system, to be installed. :term:`Wheel` is such a format, whereas :term:" -"`Source Distribution ` is not, in that " -"it requires a build step before it can be installed. This format does not " -"imply that Python files have to be precompiled (:term:`Wheel` intentionally " -"does not include compiled Python files). See :ref:`package-formats` for more " -"information." +"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 "" -":term:`配布物 `とは、ターゲットとなるシステムの適切な位" -"置に移動することでインストールされるファイルやメタデータを内包したフォーマッ" -"トです。:term:`Wheel`はそのようなフォーマットですが、他方で、distutilの :" -"term:`ソースコード配布物 ` format (usually generated " -"using ``python -m build --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`. See :ref:`package-formats` for more " -"information." +#: ../source/tutorials/packaging-projects.rst:547 +msgid "Notes" msgstr "" -":ref:`pip`のようなツールでインストールする時や :term:`ビルド配布物 ` を生成する時に必要なメタデータと必須ソースコードを提供する、" -"(通常は ``python -m build --sdist`` を使って生成される) :term:`配布物 " -"` フォーマット 。" -#: ../source/glossary.rst:269 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" -"The standard :term:`Built Distribution` format. See :ref:`package-formats` " -"for more information." +"Technically, you can also create Python packages without an ``__init__.py`` " +"file, but those are called :doc:`namespace packages ` and considered an **advanced topic** (not covered in " +"this tutorial). If you are only getting started with Python packaging, it is " +"recommended to stick with *regular packages* and ``__init__.py`` (even if " +"the file is empty)." msgstr "" +#~ msgid "Wheel vs Egg" +#~ msgstr "Wheel対Egg" + +#~ msgid "" +#~ ":term:`Wheel` and :term:`Egg` are both packaging formats that aim to " +#~ "support 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 "" +#~ ":term:`Wheel`と :term:`Egg`は、どちらも、試験目的の場合や本番環境の場合に" +#~ "はコストが高すぎるビルドやコンパイルをしなくてもプログラムをインストールす" +#~ "るというユースケースに対応することを目指したパッケージングのフォーマットで" +#~ "す。" + +#~ 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`のフォーマットは、2004年に:ref:`setuptools`によって、また、:" +#~ "term:`Wheel`のフォーマットは2012年に:pep:`427`によって導入されました。" + +#~ msgid "" +#~ ":term:`Wheel` is currently considered the standard for :term:`built " +#~ "` and :term:`binary ` packaging " +#~ "for Python." +#~ msgstr "" +#~ ":term:`Wheel`は、現在、Pythonにおける :term:`ビルド済配布物 `および :term:`バイナリ配布物 `の標準で" +#~ "あるとみなされています。" + +#~ msgid "" +#~ "Here's a breakdown of the important differences between :term:`Wheel` " +#~ "and :term:`Egg`." +#~ msgstr ":term:`Wheel`と :term:`Egg`の重要な差異について以下にまとめます。" + +#~ msgid "" +#~ ":term:`Wheel` has an :doc:`official standard specification `. :term:`Egg` did not." +#~ msgstr "" +#~ ":term:`Wheel`には :doc:`公式の標準仕様 ` が存在します。 :term:`Egg`には対応するPEPがありませ" +#~ "ん。" + +#~ msgid "" +#~ ":term:`Wheel` is a :term:`distribution ` format, i." +#~ "e a packaging format. [1]_ :term:`Egg` was both a distribution format and " +#~ "a runtime installation format (if left zipped), and was designed to be " +#~ "importable." +#~ msgstr "" +#~ ":term:`Wheel`は :term:`配布物 `のフォーマット、つま" +#~ "り、パッケージのフォーマットです。[1]_ :term:`Egg`は配布物のフォーマットで" +#~ "もあり、かつ、(もし圧縮されたままであれば)実行時のインストールフォーマット" +#~ "であってimportができるように設計されています。" + +#~ msgid "" +#~ ":term:`Wheel` archives do not include .pyc files. Therefore, when the " +#~ "distribution only contains Python files (i.e. no compiled extensions), " +#~ "and is compatible with Python 2 and 3, it's possible for a wheel to be " +#~ "\"universal\", similar to an :term:`sdist `." +#~ msgstr "" +#~ ":term:`Wheel`形式のファイルには.pycファイルが含まれていません。従って、配" +#~ "布物には(コンパイル済のファイル抜きの)Pythonファイルのみ(含み、Pythonの" +#~ "バージョン2と3で使用可能ですので、 :term:`sdist `と同様にwheelは「汎用」であると言うことができます。" + +#~ msgid "" +#~ ":term:`Wheel` uses :pep:`PEP376-compliant <376>` ``.dist-info`` " +#~ "directories. Egg used ``.egg-info``." +#~ msgstr "" +#~ ":term:`Wheel`は :pep:`PEP376-compliant <376>`に従って ``.dist-info`` ディ" +#~ "レクトリを用います。Eggは ``.egg-info`` を用います。" + +#~ msgid "" +#~ ":term:`Wheel` has a :pep:`richer file naming convention <425>`. A single " +#~ "wheel archive can indicate its compatibility with a number of Python " +#~ "language versions and implementations, ABIs, and system architectures." +#~ msgstr "" +#~ ":term:`Wheel`には:pep:`richer file naming convention <425>`が存在します。" +#~ "単独のwheelアーカイブはPython言語のバージョンや実装、ABI、そしてシステムの" +#~ "アーキテクチャとの互換性を表示することができます。" + +#~ 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の仕様や実装のバージョンを保持しています。" + +#~ msgid "" +#~ ":term:`Wheel` is internally organized by `sysconfig path type `_, therefore " +#~ "making it easier to convert to other formats." +#~ msgstr "" +#~ ":term:`Wheel`は内部では`sysconfigパスの型 `_で整理されているので、他の" +#~ "フォーマットに変換するのがより簡単になっています。" + +#~ msgid "" +#~ ":term:`Egg` uploads have been disabled for upload to PyPI, per :pep:" +#~ "`715`. Read the `deprecation notice `_ for more information." +#~ msgstr "" +#~ ":term:`Egg` によるアップロードは、 :pep:`715` に従って PyPI へのアップロー" +#~ "ドとしては無効になっています。もっと情報が欲しい場合は、 `非推奨のお知ら" +#~ "せ `_ を読んでください。" + +#~ msgid "" +#~ "A :term:`Distribution ` format containing files and " +#~ "metadata that only need to be moved to the correct location on the target " +#~ "system, to be installed. :term:`Wheel` is such a format, whereas " +#~ "distutil's :term:`Source Distribution ` is not, in that it requires a build step before it can be " +#~ "installed. This format does not imply that Python files have to be " +#~ "precompiled (:term:`Wheel` intentionally does not include compiled Python " +#~ "files)." +#~ msgstr "" +#~ ":term:`配布物 `とは、ターゲットとなるシステムの適切" +#~ "な位置に移動することでインストールされるファイルやメタデータを内包した" +#~ "フォーマットです。:term:`Wheel`はそのようなフォーマットですが、他方で、" +#~ "distutilの :term:`ソースコード配布物 ` " +#~ "and `Python Eggs `_" +#~ msgstr "" +#~ ":term:`ビルド済配布物 `フォーマットは :ref:" +#~ "`setuptools`によって導入されましたが、 :term:`Wheel`によって置き換えられつ" +#~ "つあります。詳細については、 :doc:`Python Eggsの内部構造 ` や `Python Eggs `_ を参照してください。" + +#~ msgid "" +#~ "A :term:`distribution ` format (usually generated " +#~ "using ``python -m build --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`." +#~ msgstr "" +#~ ":ref:`pip`のようなツールでインストールする時や :term:`ビルド配布物 ` を生成する時に必要なメタデータと必須ソースコードを提供す" +#~ "る、(通常は ``python -m build --sdist`` を使って生成される) :term:`配布物 " +#~ "` フォーマット 。" + +#~ msgid "" +#~ "A :term:`Built Distribution` format introduced by an official :doc:" +#~ "`standard specification `, " +#~ "which is intended to replace the :term:`Egg` format. Wheel is currently " +#~ "supported by :ref:`pip`." +#~ msgstr "" +#~ ":term:`ビルド済配布物 ` フォーマットは、 :term:`Egg` " +#~ "フォーマットを置換することを意図して、公式の :doc:`標準仕様 ` で導入されました。Wheel は、" +#~ "現時点では、 :ref:`pip` によってサポートされています。" + +#~ 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 "" +#~ "``requested_revision`` キー (``string`` 型) は、ブランチ・タグ・リファレン" +#~ "ス・コミット・リビジョンその他を指定するために存在していても構いません " +#~ "(VCS と互換性を持つフォーマットにて)。" + #~ msgid "" #~ "If you're familiar with Python packaging and installation, and just want " #~ "to know what tools are currently recommended, then here it is." @@ -29429,15 +29328,6 @@ msgstr "" #~ "``url`` は、セキュリティ上の理由から、機微に関わる認証情報をすべて削除して" #~ "おかなければなりません。" -#~ 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) " -#~ "to install." -#~ msgstr "" -#~ "``requested_revision`` キー (``string`` 型) は、どのブランチ・タグ・リファ" -#~ "レンス・コミット・リビジョンその他をインストールするのかを指定するために存" -#~ "在していても構いません。" - #~ msgid "" #~ "A ``commit_id`` key (type ``string``) MUST be present, containing the " #~ "exact commit/revision number that was installed. If the VCS supports " diff --git a/locales/ko/LC_MESSAGES/messages.po b/locales/ko/LC_MESSAGES/messages.po index eba725ab4..28f57a089 100644 --- a/locales/ko/LC_MESSAGES/messages.po +++ b/locales/ko/LC_MESSAGES/messages.po @@ -11,7 +11,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-03-21 03:01+0000\n" "Last-Translator: emscb \n" "Language-Team: Korean =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13576,7 +13578,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13584,24 +13586,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13609,22 +13611,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13635,65 +13637,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13701,106 +13703,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/lzh/LC_MESSAGES/messages.po b/locales/lzh/LC_MESSAGES/messages.po index f5f16a9ed..000a1653f 100644 --- a/locales/lzh/LC_MESSAGES/messages.po +++ b/locales/lzh/LC_MESSAGES/messages.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-01-31 06:01+0000\n" "Last-Translator: maker \n" "Language-Team: Chinese (Literary) =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13505,7 +13507,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13513,24 +13515,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13538,22 +13540,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13564,65 +13566,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13630,106 +13632,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/mk/LC_MESSAGES/messages.po b/locales/mk/LC_MESSAGES/messages.po index 79fd2c1e8..c13751a6d 100644 --- a/locales/mk/LC_MESSAGES/messages.po +++ b/locales/mk/LC_MESSAGES/messages.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2023-10-21 04:04+0000\n" "Last-Translator: \"Kristijan \\\"Fremen\\\" Velkovski\" \n" "Language-Team: Macedonian =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13509,7 +13511,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13517,24 +13519,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13542,22 +13544,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13568,65 +13570,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13634,106 +13636,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/pl/LC_MESSAGES/messages.po b/locales/pl/LC_MESSAGES/messages.po index 29d109083..19c353e1a 100644 --- a/locales/pl/LC_MESSAGES/messages.po +++ b/locales/pl/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: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -2846,7 +2846,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 #: ../source/specifications/dependency-specifiers.rst:29 -#: ../source/specifications/direct-url-data-structure.rst:342 +#: ../source/specifications/direct-url-data-structure.rst:344 #: ../source/specifications/version-specifiers.rst:1067 msgid "Examples" msgstr "" @@ -11793,7 +11793,7 @@ msgstr "" #: ../source/specifications/binary-distribution-format.rst:421 #: ../source/specifications/core-metadata.rst:848 #: ../source/specifications/dependency-specifiers.rst:476 -#: ../source/specifications/direct-url-data-structure.rst:392 +#: ../source/specifications/direct-url-data-structure.rst:394 #: ../source/specifications/direct-url.rst:67 #: ../source/specifications/entry-points.rst:164 #: ../source/specifications/externally-managed-environments.rst:472 @@ -13440,10 +13440,12 @@ msgstr "" #: ../source/specifications/direct-url-data-structure.rst:61 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)." +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:63 +#: ../source/specifications/direct-url-data-structure.rst:65 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 " @@ -13451,34 +13453,34 @@ msgid "" "``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:71 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "Archive URLs" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/direct-url-data-structure.rst:75 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/direct-url-data-structure.rst:76 +#: ../source/specifications/direct-url-data-structure.rst:78 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/direct-url-data-structure.rst:79 +#: ../source/specifications/direct-url-data-structure.rst:81 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:83 +#: ../source/specifications/direct-url-data-structure.rst:85 msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/direct-url-data-structure.rst:87 msgid "" "Any hash algorithm available via :py:mod:`hashlib` (specifically any that " "can be passed to :py:func:`hashlib.new()` and do not require additional " @@ -13487,13 +13489,13 @@ msgid "" "be included. At time of writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:91 +#: ../source/specifications/direct-url-data-structure.rst:93 msgid "" "A deprecated ``hash`` key (type ``string``) MAY be present for backwards " "compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13501,7 +13503,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13509,24 +13511,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13534,22 +13536,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13560,65 +13562,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13626,106 +13628,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/pt_BR/LC_MESSAGES/messages.po b/locales/pt_BR/LC_MESSAGES/messages.po index 850101a55..b6088fdba 100644 --- a/locales/pt_BR/LC_MESSAGES/messages.po +++ b/locales/pt_BR/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: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-03-01 20:00+0000\n" "Last-Translator: Rafael Fontenelle \n" "Language-Team: Portuguese (Brazil) =``." @@ -18039,7 +18046,7 @@ msgstr "" "fins de compatibilidade com versões anteriores, com valor ``=``." -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -18051,7 +18058,7 @@ msgstr "" "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:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -18063,11 +18070,11 @@ msgstr "" "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:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "Diretórios locais" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 msgid "" "When ``url`` refers to a local directory, the ``dir_info`` key MUST be " "present as a dictionary with the following key:" @@ -18075,7 +18082,7 @@ 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:108 +#: ../source/specifications/direct-url-data-structure.rst:110 msgid "" "``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " "installed in editable mode, ``false`` otherwise. If absent, default to " @@ -18085,7 +18092,7 @@ msgstr "" "instalada em modo editável, ``false`` caso contrário. Se ausente, é usado o " "padrão ``false``." -#: ../source/specifications/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -18097,11 +18104,11 @@ msgstr "" "caminho deve ser absoluto. Links simbólicos DEVERIAM ser preservados ao " "tornar os caminhos relativos absolutos." -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "Projetos em subdiretórios" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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 " @@ -18112,11 +18119,11 @@ msgstr "" "diretório local, para especificar onde ``pyproject.toml`` ou ``setup.py`` " "está localizado." -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "VCS registrados" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -18135,48 +18142,48 @@ msgstr "" "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:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "Git" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "Site" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "https://git-scm.com/" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "Comando vcs" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "git" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "Campo ``vcs``" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "Campo ``requested_revision``" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 msgid "" "A tag name, branch name, Git ref, commit hash, shortened commit hash, or " "other commit-ish." @@ -18184,18 +18191,18 @@ 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "Campo ``commit_id``" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 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:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -18208,64 +18215,64 @@ msgstr "" "ref começando com ``refs/remotes/origin/`` após a clonagem corresponde a um " "branch." -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "Mercurial" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "hg" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 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/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "Um ID de changeset (40 caracteres hexadecimais)." -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "Bazaar" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 #, fuzzy msgid "https://www.breezy-vcs.org/" msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "bzr" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "Um nome de tag, nome de branch, id de revisão." -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "Um id de revisão." -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "svn" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." @@ -18273,7 +18280,7 @@ 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:215 +#: ../source/specifications/direct-url-data-structure.rst:217 msgid "" "Since Subversion does not support globally unique identifiers, this field is " "the Subversion revision number in the corresponding repository." @@ -18282,39 +18289,39 @@ msgstr "" "únicos, este campo é o número da revisão do Subversion no repositório " "correspondente." -#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "Arquivo fonte:" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "URL Git com tag e hash de commit:" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "Diretório local:" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "Diretório local em modo editável:" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 #, fuzzy msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion \n" "Language-Team: Romanian =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13507,7 +13509,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13515,24 +13517,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13540,22 +13542,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13566,65 +13568,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13632,106 +13634,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/ru/LC_MESSAGES/messages.po b/locales/ru/LC_MESSAGES/messages.po index 2281ca034..bd13a7c33 100644 --- a/locales/ru/LC_MESSAGES/messages.po +++ b/locales/ru/LC_MESSAGES/messages.po @@ -13,7 +13,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-03-31 15:01+0000\n" "Last-Translator: Nikita \n" "Language-Team: Russian =``." @@ -17930,7 +17936,7 @@ msgstr "" "Устаревший ключ ``hash`` (тип ``string``) МОЖЕТ присутствовать в целях " "обратной совместимости, со значением ``=``." -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -17942,7 +17948,7 @@ msgstr "" "выдавать ключ ``hash`` в тех контекстах, где они делали это раньше, чтобы " "сохранить обратную совместимость для существующих клиентов." -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -17954,11 +17960,11 @@ msgstr "" "могут рассматривать ключ ``hashes``, только если он присутствует, и " "возвращаться к ``hash`` в противном случае." -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "Локальные каталоги" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 msgid "" "When ``url`` refers to a local directory, the ``dir_info`` key MUST be " "present as a dictionary with the following key:" @@ -17966,7 +17972,7 @@ msgstr "" "Когда ``url`` ссылается на локальный каталог, ключ ``dir_info`` ДОЛЖЕН " "присутствовать в виде словаря со следующим ключом:" -#: ../source/specifications/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 msgid "" "``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " "installed in editable mode, ``false`` otherwise. If absent, default to " @@ -17976,7 +17982,7 @@ msgstr "" "установлен в редактируемом режиме, ``false`` в противном случае. Если " "отсутствует, то по умолчанию ``false``." -#: ../source/specifications/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -17988,11 +17994,11 @@ msgstr "" "абсолютным. Символьные ссылки ДОЛЖНЫ сохраняться при преобразовании " "относительных путей в абсолютные." -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "Проекты в подкаталогах" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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 " @@ -18002,11 +18008,11 @@ msgstr "" "относительно корня VCS-репозитория, исходного архива или локального " "каталога, чтобы указать, где находится ``pyproject.toml`` или ``setup.py``." -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "Зарегистрированный VCS" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -18025,48 +18031,48 @@ msgstr "" "команды (в нижнем регистре). Дополнительные поля, необходимые для поддержки " "такой VCS, ДОЛЖНЫ иметь префикс с именем команды VCS." -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "Git" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "Домашняя страница" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "https://git-scm.com/" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "команда vcs" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "git" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "поле ``vcs``" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "поле ``запрошенный_пересмотр``" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 msgid "" "A tag name, branch name, Git ref, commit hash, shortened commit hash, or " "other commit-ish." @@ -18074,18 +18080,18 @@ msgstr "" "Имя тега, имя ветки, Git ref, хэш коммита, сокращённый хэш коммита или " "другое имя коммита." -#: ../source/specifications/direct-url-data-structure.rst:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "поле ``commit_id``" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "Хэш фиксации (40 шестнадцатеричных символов sha1)." -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -18098,64 +18104,64 @@ msgstr "" "соответствует тегу, а ссылка, начинающаяся с ``refs/remotes/origin/`` после " "клонирования, соответствует ветке." -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "Mercurial" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "hg" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" "Имя тега, имя ветки, идентификатор набора изменений, сокращенный " "идентификатор набора изменений." -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "Идентификатор набора изменений (40 шестнадцатеричных символов)." -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "Bazaar" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "https://www.breezy-vcs.org/" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "bzr" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "Имя тега, имя ветки, идентификатор ревизии." -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "Идентификатор ревизии." -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "svn" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." @@ -18163,7 +18169,7 @@ msgstr "" "``requested_revision`` должен быть совместим с опцией ``vn checkout`` ``--" "revision``. В Subversion ветка или тег являются частью ``url``." -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 msgid "" "Since Subversion does not support globally unique identifiers, this field is " "the Subversion revision number in the corresponding repository." @@ -18172,33 +18178,33 @@ msgstr "" "это поле представляет собой номер ревизии Subversion в соответствующем " "хранилище." -#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "Архив источников:" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "URL-адрес Git с тегом и хэшем фиксации:" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "Локальный справочник:" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "Локальная директория в режиме редактирования:" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." @@ -18206,7 +18212,7 @@ msgstr "" "Март 2020 года: Эта спецификация была одобрена через :pep:`610`, определяя " "файл метаданных ``direct_url.json``." -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/sai/LC_MESSAGES/messages.po b/locales/sai/LC_MESSAGES/messages.po index 0474ba9fe..1a9ec8590 100644 --- a/locales/sai/LC_MESSAGES/messages.po +++ b/locales/sai/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: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -2846,7 +2846,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 #: ../source/specifications/dependency-specifiers.rst:29 -#: ../source/specifications/direct-url-data-structure.rst:342 +#: ../source/specifications/direct-url-data-structure.rst:344 #: ../source/specifications/version-specifiers.rst:1067 msgid "Examples" msgstr "" @@ -11793,7 +11793,7 @@ msgstr "" #: ../source/specifications/binary-distribution-format.rst:421 #: ../source/specifications/core-metadata.rst:848 #: ../source/specifications/dependency-specifiers.rst:476 -#: ../source/specifications/direct-url-data-structure.rst:392 +#: ../source/specifications/direct-url-data-structure.rst:394 #: ../source/specifications/direct-url.rst:67 #: ../source/specifications/entry-points.rst:164 #: ../source/specifications/externally-managed-environments.rst:472 @@ -13440,10 +13440,12 @@ msgstr "" #: ../source/specifications/direct-url-data-structure.rst:61 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)." +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:63 +#: ../source/specifications/direct-url-data-structure.rst:65 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 " @@ -13451,34 +13453,34 @@ msgid "" "``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:71 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "Archive URLs" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/direct-url-data-structure.rst:75 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/direct-url-data-structure.rst:76 +#: ../source/specifications/direct-url-data-structure.rst:78 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/direct-url-data-structure.rst:79 +#: ../source/specifications/direct-url-data-structure.rst:81 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:83 +#: ../source/specifications/direct-url-data-structure.rst:85 msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/direct-url-data-structure.rst:87 msgid "" "Any hash algorithm available via :py:mod:`hashlib` (specifically any that " "can be passed to :py:func:`hashlib.new()` and do not require additional " @@ -13487,13 +13489,13 @@ msgid "" "be included. At time of writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:91 +#: ../source/specifications/direct-url-data-structure.rst:93 msgid "" "A deprecated ``hash`` key (type ``string``) MAY be present for backwards " "compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13501,7 +13503,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13509,24 +13511,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13534,22 +13536,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13560,65 +13562,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13626,106 +13628,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/si/LC_MESSAGES/messages.po b/locales/si/LC_MESSAGES/messages.po index ee14bba0b..d5920189b 100644 --- a/locales/si/LC_MESSAGES/messages.po +++ b/locales/si/LC_MESSAGES/messages.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2022-06-11 08:19+0000\n" "Last-Translator: Kushan Gunasekera \n" "Language-Team: Sinhala =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13505,7 +13507,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13513,24 +13515,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13538,22 +13540,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13564,65 +13566,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13630,106 +13632,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/sk/LC_MESSAGES/messages.po b/locales/sk/LC_MESSAGES/messages.po index 74be452d4..457a21235 100644 --- a/locales/sk/LC_MESSAGES/messages.po +++ b/locales/sk/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: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2023-09-21 05:16+0000\n" "Last-Translator: Milan Šalka \n" "Language-Team: Slovak =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13638,7 +13640,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13646,24 +13648,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13671,22 +13673,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13697,65 +13699,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13763,106 +13765,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/uk/LC_MESSAGES/messages.po b/locales/uk/LC_MESSAGES/messages.po index 683d8e7f0..e6115d84c 100644 --- a/locales/uk/LC_MESSAGES/messages.po +++ b/locales/uk/LC_MESSAGES/messages.po @@ -15,7 +15,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-03-01 20:00+0000\n" "Last-Translator: Sviatoslav Sydorenko \n" "Language-Team: Ukrainian =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -14008,7 +14010,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -14016,24 +14018,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -14041,22 +14043,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -14067,65 +14069,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "Git" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "Домашня сторінка" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "https://git-scm.com/" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "git" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -14133,108 +14135,108 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "Mercurial" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "hg" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "Bazaar" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 #, 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:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "bzr" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "Subversion" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "https://subversion.apache.org/" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "svn" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/zh_Hans/LC_MESSAGES/messages.po b/locales/zh_Hans/LC_MESSAGES/messages.po index 103f4d7de..0e554ebe3 100644 --- a/locales/zh_Hans/LC_MESSAGES/messages.po +++ b/locales/zh_Hans/LC_MESSAGES/messages.po @@ -29,7 +29,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2024-04-04 03:43+0000\n" "Last-Translator: 大王叫我来巡山 \n" @@ -2675,8 +2675,8 @@ msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." msgstr "" -"一种 :term:`构建分发` 格式，由 :ref:`setuptools` 引入，已被 :term:`Wheel` " -"替代。详见： :ref:`egg-format`." +"一种 :term:`构建分发` 格式，由 :ref:`setuptools` 引入，已被 :term:`Wheel` 替" +"代。详见： :ref:`egg-format`." #: ../source/glossary.rst:78 msgid "Extension Module" @@ -3217,7 +3217,7 @@ msgstr "描述" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 #: ../source/specifications/dependency-specifiers.rst:29 -#: ../source/specifications/direct-url-data-structure.rst:342 +#: ../source/specifications/direct-url-data-structure.rst:344 #: ../source/specifications/version-specifiers.rst:1067 msgid "Examples" msgstr "例子" @@ -12537,7 +12537,7 @@ msgstr "" #: ../source/specifications/binary-distribution-format.rst:421 #: ../source/specifications/core-metadata.rst:848 #: ../source/specifications/dependency-specifiers.rst:476 -#: ../source/specifications/direct-url-data-structure.rst:392 +#: ../source/specifications/direct-url-data-structure.rst:394 #: ../source/specifications/direct-url.rst:67 #: ../source/specifications/entry-points.rst:164 #: ../source/specifications/externally-managed-environments.rst:472 @@ -14193,10 +14193,12 @@ msgstr "" #: ../source/specifications/direct-url-data-structure.rst:61 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)." +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:63 +#: ../source/specifications/direct-url-data-structure.rst:65 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 " @@ -14204,34 +14206,34 @@ msgid "" "``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:71 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "Archive URLs" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/direct-url-data-structure.rst:75 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/direct-url-data-structure.rst:76 +#: ../source/specifications/direct-url-data-structure.rst:78 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/direct-url-data-structure.rst:79 +#: ../source/specifications/direct-url-data-structure.rst:81 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:83 +#: ../source/specifications/direct-url-data-structure.rst:85 msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/direct-url-data-structure.rst:87 msgid "" "Any hash algorithm available via :py:mod:`hashlib` (specifically any that " "can be passed to :py:func:`hashlib.new()` and do not require additional " @@ -14240,13 +14242,13 @@ msgid "" "be included. At time of writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:91 +#: ../source/specifications/direct-url-data-structure.rst:93 msgid "" "A deprecated ``hash`` key (type ``string``) MAY be present for backwards " "compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -14254,7 +14256,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -14262,24 +14264,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -14287,22 +14289,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "子目录中的项目" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -14313,65 +14315,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -14379,106 +14381,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." diff --git a/locales/zh_Hant/LC_MESSAGES/messages.po b/locales/zh_Hant/LC_MESSAGES/messages.po index 4eb9654a9..3392e4bb6 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: 2024-04-03 17:18+0000\n" +"POT-Creation-Date: 2024-04-13 15:31+0000\n" "PO-Revision-Date: 2022-07-30 20:04+0000\n" "Last-Translator: meowmeowmeowcat \n" "Language-Team: Chinese (Traditional) =``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:94 +#: ../source/specifications/direct-url-data-structure.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 " @@ -13620,7 +13622,7 @@ msgid "" "compatibility for existing clients." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:98 +#: ../source/specifications/direct-url-data-structure.rst:100 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 " @@ -13628,24 +13630,24 @@ msgid "" "back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:103 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "Local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/direct-url-data-structure.rst:107 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/direct-url-data-structure.rst:108 +#: ../source/specifications/direct-url-data-structure.rst:110 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/direct-url-data-structure.rst:111 +#: ../source/specifications/direct-url-data-structure.rst:113 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 " @@ -13653,22 +13655,22 @@ msgid "" "absolute." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:117 +#: ../source/specifications/direct-url-data-structure.rst:119 msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:119 +#: ../source/specifications/direct-url-data-structure.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." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:124 +#: ../source/specifications/direct-url-data-structure.rst:126 msgid "Registered VCS" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:128 msgid "" "This section lists the registered VCS's; expanded, VCS-specific information " "on how to use the ``vcs``, ``requested_revision``, and other fields of " @@ -13679,65 +13681,65 @@ msgid "" "VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:138 msgid "Git" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:141 +#: ../source/specifications/direct-url-data-structure.rst:168 +#: ../source/specifications/direct-url-data-structure.rst:186 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "Home page" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:141 msgid "https://git-scm.com/" msgstr "" -#: ../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 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:207 msgid "vcs command" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:142 -#: ../source/specifications/direct-url-data-structure.rst:145 +#: ../source/specifications/direct-url-data-structure.rst:144 +#: ../source/specifications/direct-url-data-structure.rst:147 msgid "git" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:145 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:190 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:147 +#: ../source/specifications/direct-url-data-structure.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:192 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "``vcs`` field" msgstr "" -#: ../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:212 +#: ../source/specifications/direct-url-data-structure.rst:151 +#: ../source/specifications/direct-url-data-structure.rst:177 +#: ../source/specifications/direct-url-data-structure.rst:195 +#: ../source/specifications/direct-url-data-structure.rst:214 msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:148 +#: ../source/specifications/direct-url-data-structure.rst:150 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:152 -#: ../source/specifications/direct-url-data-structure.rst:178 -#: ../source/specifications/direct-url-data-structure.rst:196 -#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:180 +#: ../source/specifications/direct-url-data-structure.rst:198 +#: ../source/specifications/direct-url-data-structure.rst:219 msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:152 +#: ../source/specifications/direct-url-data-structure.rst:154 msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:156 +#: ../source/specifications/direct-url-data-structure.rst:158 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 " @@ -13745,106 +13747,106 @@ msgid "" "with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:165 msgid "Mercurial" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:168 msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:169 -#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:171 +#: ../source/specifications/direct-url-data-structure.rst:174 msgid "hg" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:177 msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 +#: ../source/specifications/direct-url-data-structure.rst:180 msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:183 msgid "Bazaar" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:186 msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:192 msgid "bzr" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:195 msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:196 +#: ../source/specifications/direct-url-data-structure.rst:198 msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:201 msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:204 msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:207 +#: ../source/specifications/direct-url-data-structure.rst:210 msgid "svn" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:213 msgid "" "``requested_revision`` must be compatible with ``svn checkout`` ``--" "revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:215 +#: ../source/specifications/direct-url-data-structure.rst:217 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:220 +#: ../source/specifications/direct-url-data-structure.rst:222 msgid "JSON Schema" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:222 +#: ../source/specifications/direct-url-data-structure.rst:224 msgid "" "The following JSON Schema can be used to validate the contents of " "``direct_url.json``:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:344 +#: ../source/specifications/direct-url-data-structure.rst:346 msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:357 +#: ../source/specifications/direct-url-data-structure.rst:359 msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:370 +#: ../source/specifications/direct-url-data-structure.rst:372 msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:379 +#: ../source/specifications/direct-url-data-structure.rst:381 msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:394 +#: ../source/specifications/direct-url-data-structure.rst:396 msgid "" "March 2020: This specification was approved through :pep:`610`, defining the " "``direct_url.json`` metadata file." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:396 +#: ../source/specifications/direct-url-data-structure.rst:398 msgid "" "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)."